From 2a28fc7d4e87d70e267d64fac9ee3e957a33bfa0 Mon Sep 17 00:00:00 2001 From: OrcaWin Date: Sun, 25 Oct 2026 04:20:32 -0700 Subject: [PATCH] [comment audit] Finish launcher and configuration comment review (#33513) Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com> --- .gitattributes | 48 ++++++++---------------------- .github/CODEOWNERS | 2 -- .gitignore | 38 ++++------------------- cloud/.gitignore | 4 +-- config/scripts/orca-dev | 3 +- docs/site/.gitignore | 2 -- resources/darwin/bin/orca | 4 +-- resources/linux/bin/orca-ide | 11 ++----- tests/tools/relay-bench/.gitignore | 3 +- 9 files changed, 25 insertions(+), 90 deletions(-) diff --git a/.gitattributes b/.gitattributes index 0fb2aec07c4..872da5c6bcf 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,6 +1,4 @@ -# A shebang plus CRLF makes vite's SSR transform emit a literal `#!` mid-module, -# so any suite importing the script dies at load with a SyntaxError. Pin the whole -# directory rather than the scripts that happen to have a test today. +# CRLF shebangs break Vite's SSR transform. /config/scripts/**/*.mjs text eol=lf /skill-guides/*.md text eol=lf /skill-stubs/*.md text eol=lf @@ -15,55 +13,33 @@ *.html text eol=lf # Bundled plugin trees are byte-hashed; CRLF checkout would break the pinned hash. /resources/plugins/** text eol=lf -# Relay assets are copied verbatim into the bundle and hashed byte-for-byte into -# .version, which names the immutable remote install dir. A CRLF checkout makes a -# Windows-built client disagree with a mac/Linux-built one on the same release, -# so one host ends up with two relay trees (#17886 review). -# Pin the bytes so a patch reads and diffs identically on every host. It is NOT -# what makes the hash right: pnpm hashes a patch LF-normalized, so a CRLF checkout -# cannot change it. Believing otherwise put a hand-computed raw digest in the -# lockfile twice and broke every install (#17886). -# These files are stored LF, which is not always the encoding they were written -# against -- @vscode/windows-process-tree ships CRLF sources -- so any code that -# runs `git apply` on one must force `-c core.autocrlf=input` rather than trust -# the host's setting. See config/scripts/windows-process-tree-gyp-rebuild.mjs. +# Keep patch diffs stable; pnpm hashes them with LF normalization. +# CRLF upstream sources still need git -c core.autocrlf=input apply (windows-process-tree-gyp-rebuild.mjs). /config/patches/*.patch -text -# Same reason, and pnpm parses these too: a CRLF checkout makes the mobile -# patches unparseable, so Windows packaging dies on ERR_PNPM_INVALID_PATCH. +# CRLF patches fail pnpm parsing on Windows. /mobile/patches/*.patch -text -# The xterm bundle hunks also make a diff nobody can read; review the hand-written -# source patch under xterm-src/ instead. The sibling patches stay diffable. +# Review xterm-src/ instead of generated bundle hunks. /config/patches/@xterm__xterm@*.patch -diff /config/patches/xterm-src/*.patch text eol=lf # pnpm parses these unified diffs during Windows installs; keep checkout bytes stable. /mobile/patches/*.patch -text -# Generated wrapper fixtures: collapse them in the PR diff so they stop drowning -# the reviewable change, and pin LF because they are compared byte-for-byte. -# Not -diff: the shell diff is the review surface when a wrapper does change. +# Collapse generated wrappers but keep diffs available; tests compare LF bytes. /src/main/__fixtures__/shell-wrapper-snapshots/*.txt linguist-generated=true text eol=lf -# Captured agent PTY transcripts. -text, not `text eol=lf` like the wrapper snapshots above: -# these carry real CR and CRLF bytes as the terminal emitted them, and line-ending -# normalisation on a Windows checkout would rewrite the evidence the fixture exists to be. +# PTY transcripts must retain captured CR and CRLF bytes. /src/main/runtime/__fixtures__/*.txt -text /src/main/daemon/__fixtures__/pty-transcripts/*.txt -text /src/renderer/src/components/terminal-pane/terminal-link-transcripts/*.txt -text whitespace=cr-at-eol -# Generated runtime English subset: compared byte-for-byte by -# verify:localization-runtime-catalog, so a CRLF checkout would fail the gate. +# verify:localization-runtime-catalog compares LF bytes. /src/renderer/src/i18n/en-runtime-required.json linguist-generated=true text eol=lf -# Generated method->params catalog: compared byte-for-byte by -# verify:rpc-params-catalog, so a CRLF checkout would fail the gate. +# verify:rpc-params-catalog compares LF bytes. /src/shared/rpc-contract/rpc-params-catalog.generated.ts linguist-generated=true text eol=lf -# Mobile RPC recording goldens: replay requires the file text to equal what rpc:record writes -# (LF), so a CRLF checkout would fail every golden. +# RPC recording goldens must match rpc:record's LF output. /mobile/rpc-foundation/goldens/*.json text eol=lf -# Mobile web page source. Every text byte here is hashed into an asset digest and from -# there into buildId, so a CRLF Windows checkout would ship a different bundle id for -# identical source (91af2897 vs 9d78435e, measured on the bundle this replaced). +# Mobile build IDs hash source bytes; checkout line endings must match across hosts. /mobile/src/** text eol=lf /mobile/app/** text eol=lf /mobile/web-entry/** text eol=lf -# The blanket pin above would mark a future binary as text; exempt the asset types an -# RN page actually carries. +# Preserve binary assets under the text-pinned mobile directories. /mobile/src/**/*.png -text /mobile/src/**/*.jpg -text /mobile/src/**/*.jpeg -text diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dc1c1412470..366407beb7a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,10 +1,8 @@ -# Product source remains owned by its normal reviewers; localization inputs need focused review. /src/renderer/src/i18n/locales/ @brennanb2025 /config/scripts/*localization*.mjs @brennanb2025 /config/scripts/*locale*.mjs @brennanb2025 /config/i18next.config.ts @brennanb2025 -# The relay's deploy and operate surface: workspace, workflows, and the rollout lease action. /cloud/ @Jinwoo-H /.github/workflows/cloud-*.yml @Jinwoo-H /.github/actions/cloud-sql-rollout-lease/ @Jinwoo-H diff --git a/.gitignore b/.gitignore index ffa6ea54cde..0c9b1cb2c55 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,6 @@ -# Build artifacts tsconfig.*.tsbuildinfo -# TypeScript emit artifacts next to sources (tsc produced these accidentally; -# real source lives in .ts/.tsx). Hand-authored declaration files are -# re-included below. +# Exclude accidental tsc output; retain hand-authored declarations below. src/**/*.js src/**/*.d.ts /electron.vite.config.js @@ -15,13 +12,10 @@ src/**/*.d.ts !src/renderer/src/mermaid.d.ts !src/types/build-constants.d.ts -# Dependencies node_modules/ -# Why: the trailing-slash form matches directories only, so a node_modules SYMLINK (how agent -# worktrees share an install) slipped past a bulk `git add` and got committed — twice. +# Match symlinked installs too; the trailing-slash pattern only matches directories. node_modules -# Build output dist/ dist-electron/ out/ @@ -37,16 +31,13 @@ native/windows-security/build/ native/windows-security/bin/ .build/windows-security/ -# pnpm .pnpm-store/ package-lock.json -# Environment .env .env.local .env.*.local -# IDE .vscode/ .idea/ .serena/ @@ -54,10 +45,7 @@ package-lock.json *.swo *~ -# OS -# Keep these in step with isOsMetadataSkillEntryName (skill-package-identity.ts): both disk -# walkers skip a plain file with one of these names, the git-tree producer does not, and -# ignoring them here is what keeps `git add -A` from committing a stray one. +# Keep metadata exclusions in sync with isOsMetadataSkillEntryName (skill-package-identity.ts). *.stackdump .DS_Store ._* @@ -65,7 +53,6 @@ Thumbs.db ehthumbs.db desktop.ini -# Lint/cache .oxlintcache /.cache/vite/ /.cache/vite.lock/ @@ -73,13 +60,11 @@ desktop.ini /.cache/fixtures/ /.cache/check-changed.json -# Logs *.log *.log.* npm-debug.log* pnpm-debug.log* -# Coverage coverage/ # Prod release scan output (accidental adds) @@ -89,7 +74,6 @@ prod-release-scan-*.md /tests/tools/benchmarks/results/*.json /.bench-fixtures/ -# Temp tmp/ .tmp/ design-docs/ @@ -99,12 +83,9 @@ design-docs/ # Machine-local agent hook endpoint files may contain auth tokens. /agent-hooks/ -# Local-only design/planning docs (not checked in). -# Durable docs that should be tracked must live in one of the allow-listed -# locations below (assets, readme, STYLEGUIDE + styleguide/, and mobile terminal shortcut bar). +# Planning docs stay local; allow durable documentation below. docs/** !docs/ -# The deployable docs app is source, not local engineering notes. !docs/site/ !docs/site/** !docs/assets/ @@ -124,7 +105,6 @@ docs/** !docs/agent-skill-sharing-implementation-checklist.md !docs/mobile-terminal-shortcut-bar.md -# Stably CLI (only docs/ are tracked) .stably/* !.stably/docs/ .playwright-cli @@ -136,11 +116,10 @@ validation-screenshots/ /notes/ /pr-evidence/ -# Playwright test-results/ playwright-report/ -# Agent skill installations (machine-local, populated by agent tooling) +# Agent skills are installed per machine. /.claude/skills/ /.agents/skills/ /skills-lock.json @@ -153,22 +132,18 @@ playwright-report/ /agent-hooks/ validation-screenshots/ -# Localization bootstrap cache (regenerated by bootstrap:*-catalog) src/renderer/src/i18n/locales/.zh-catalog-cache.json src/renderer/src/i18n/locales/.ko-catalog-cache.json src/renderer/src/i18n/locales/.ja-catalog-cache.json src/renderer/src/i18n/locales/.es-catalog-cache.json src/renderer/src/i18n/locales/.fr-catalog-cache.json -# Bench result JSONs are working artifacts tests/tools/benchmarks/results/terminal-pipeline-*.json # Old release trees the cross-version wire harness extracts on demand tests/e2e/.cross-version-checkouts/ -# Bundler's install path for the mobile release toolchain (mobile/Gemfile.lock -# IS committed). Also keeps oxfmt/oxlint, which honor this file, from walking -# vendored gems. +# Bundler installs gems here; keep linters out of the vendored tree. /mobile/vendor/ # Generated by config/scripts/sync-anti-slop-plugin.mjs from the pinned oxlint-plugin-anti-slop @@ -177,7 +152,6 @@ tests/e2e/.cross-version-checkouts/ # Generated by the CI unit-test sequencer (and by reproducing a shard locally). ci-shards/ -# Paired CI timing reports and temporary baseline plugin. .build/preflight-benchmark/ /.build/windows-native-benchmark/ diff --git a/cloud/.gitignore b/cloud/.gitignore index 8105ed487f9..25fa859aeb5 100644 --- a/cloud/.gitignore +++ b/cloud/.gitignore @@ -8,7 +8,6 @@ coverage/ .env.local.generated *.log -# Terraform/OpenTofu local state and plans must stay out of git. **/.terraform/ *.tfstate *.tfstate.* @@ -19,6 +18,5 @@ override.tf.json *_override.tf *_override.tf.json -# Local dev signing key + SQLite live under data/ — never commit (contains a -# private key and dev PII). Prod supplies the key via ORCA_CLOUD_SIGNING_KEY_PEM. +# Contains development signing keys and personal data. data/ diff --git a/config/scripts/orca-dev b/config/scripts/orca-dev index 10754fe4ca3..9957cd03f78 100755 --- a/config/scripts/orca-dev +++ b/config/scripts/orca-dev @@ -1,8 +1,7 @@ #!/usr/bin/env bash -# Dev CLI wrapper — uses a separate userData path to avoid clobbering production Orca data. +# Keep development CLI data separate from production. set -euo pipefail -# Resolve through symlinks so this works when called via /usr/local/bin/orca-dev SOURCE="$0" while [ -L "$SOURCE" ]; do DIR="$(cd "$(dirname "$SOURCE")" && pwd)" diff --git a/docs/site/.gitignore b/docs/site/.gitignore index 4b2d8ee5e24..0c3fea39d81 100644 --- a/docs/site/.gitignore +++ b/docs/site/.gitignore @@ -5,7 +5,5 @@ out .vercel next-env.d.ts *.tsbuildinfo -# Keep local deployment credentials out of the publication boundary. .env .env.* -# Package policy lives in pnpm-workspace.yaml; keep credentials in user-level npm config. diff --git a/resources/darwin/bin/orca b/resources/darwin/bin/orca index 4d01b9928ca..fd415b25ccc 100755 --- a/resources/darwin/bin/orca +++ b/resources/darwin/bin/orca @@ -20,9 +20,7 @@ fi CONTENTS="$APP_PATH/Contents" ELECTRON="$CONTENTS/MacOS/Orca" -# Why: Orca packages the CLI entrypoint outside app.asar so the public shell -# command can execute it directly with ELECTRON_RUN_AS_NODE, mirroring VS Code's -# launcher model instead of requiring a separate npm-distributed binary. +# The unpacked entrypoint runs directly in Electron's Node mode. CLI="$CONTENTS/Resources/app.asar.unpacked/out/cli/index.js" export ORCA_NODE_OPTIONS="${NODE_OPTIONS-}" diff --git a/resources/linux/bin/orca-ide b/resources/linux/bin/orca-ide index f191f27c770..2c9130209a2 100755 --- a/resources/linux/bin/orca-ide +++ b/resources/linux/bin/orca-ide @@ -1,8 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -# Why: invoked via ~/.local/bin/orca-ide symlink (from CliInstaller); resolve it -# so APP_DIR points at the real install, not the symlink's parent. +# Installed commands are symlinks; locate resources relative to their target. SOURCE="${BASH_SOURCE[0]}" while [ -h "$SOURCE" ]; do DIR="$(cd "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)" @@ -13,8 +12,7 @@ SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)" RESOURCES_DIR="$(cd "$SCRIPT_DIR/.." >/dev/null 2>&1 && pwd)" APP_DIR="$(cd "$RESOURCES_DIR/.." >/dev/null 2>&1 && pwd)" -# Why: Linux executableName is `orca-ide` (avoids Ubuntu GNOME Orca conflict); -# `-f` rejects a same-named directory that `-x` alone would accept. +# orca-ide avoids the GNOME Orca name; -f excludes executable directories. ELECTRON="" for candidate in orca-ide orca Orca; do if [ -f "$APP_DIR/$candidate" ] && [ -x "$APP_DIR/$candidate" ]; then @@ -28,9 +26,7 @@ if [ -z "$ELECTRON" ]; then exit 1 fi -# Why: Orca packages the CLI entrypoint outside app.asar so the public shell -# command can execute it directly with ELECTRON_RUN_AS_NODE, mirroring the same -# launcher model used on macOS instead of maintaining a separate Node binary. +# The unpacked entrypoint runs directly in Electron's Node mode. CLI="$RESOURCES_DIR/app.asar.unpacked/out/cli/index.js" export ORCA_NODE_OPTIONS="${NODE_OPTIONS-}" @@ -38,5 +34,4 @@ export ORCA_NODE_REPL_EXTERNAL_MODULE="${NODE_REPL_EXTERNAL_MODULE-}" unset NODE_OPTIONS unset NODE_REPL_EXTERNAL_MODULE -# CLI commands run in Electron's Node mode and must never initialize Chromium. ELECTRON_RUN_AS_NODE=1 exec "$ELECTRON" "$CLI" "$@" diff --git a/tests/tools/relay-bench/.gitignore b/tests/tools/relay-bench/.gitignore index c4959241eb8..64caee5eff3 100644 --- a/tests/tools/relay-bench/.gitignore +++ b/tests/tools/relay-bench/.gitignore @@ -1,4 +1,3 @@ -# The bench writes a resume-credential bundle here. It carries a live device token and -# resume token for a real paired desktop; it must never reach the repo. +# Bench output contains live device and resume tokens. *.json state*