cli: --dev/--prod presets, --help, subcommand valtown (renamed)

Three coordinated changes.

1. --dev / --prod presets on generate/serve/watch:
   --dev   local-friendly (no minify, no base-path).
   --prod  GH Pages-shaped (--minify + --base-path=/socket-packageurl-js).
   No preset → auto-pick via `'CI' in process.env`:
     CI set (GitHub Actions etc.) → prod.
     CI unset (local) → dev.
   Explicit --minify / --base-path= still work and override piecewise.
   This removes duplicate flag strings from package.json scripts and CI
   workflows; the CLI + env are the single source of truth.

2. Rename deploy-val → valtown:
   - Subcommand: `pnpm walkthrough valtown`
   - Function:   deployVal → deployValtown
   - Workflow:   .github/workflows/deploy-val.yml → valtown.yml
   - npm script: walkthrough:val → walkthrough:valtown
   Matches the bare-word subcommand convention (generate, serve, watch,
   token, doctor) rather than the hyphenated verb.

3. --help / -h:
   `pnpm walkthrough --help` (and -h, and bare walkthrough) prints
   usage to stdout with exit 0. Unknown subcommands still go to stderr
   with exit 1 and a pointer to --help, rather than dumping the whole
   usage block.

package.json scripts collapse — the old `walkthrough:build:prod` went
away; `walkthrough:build` relies on the CLI to pick the right mode
based on the `CI` env var.

pages.yml + valtown.yml updated to match the new names; pages now
just runs `pnpm walkthrough:build` (CI env auto-selects --prod).

Author: jdalton

.github/workflows/pages.yml

@@ -11,11 +11,11 @@ name: 📘 Walkthrough (GH Pages)
 #
 # Build model:
 #   1. Shared setup-and-install → checkout w/ submodules, pnpm install.
-#   2. `pnpm walkthrough --minify --base-path=/socket-packageurl-js generate walkthrough.json`
-#      The --base-path flag rewrites root-relative asset URLs and Val-Town
-#      part links (/<slug>/part/<n>) into prefixed flat HTML paths so the
-#      output works at socketdev.github.io/socket-packageurl-js/. --minify
-#      runs esbuild on JS + lightningcss on CSS (~49% on-disk reduction).
+#   2. `pnpm walkthrough:build` — the `CI` env var (set by all GitHub
+#      Actions runners) makes this auto-select the `prod` preset, which
+#      applies --minify + --base-path=/socket-packageurl-js. Locally the
+#      same script defaults to `dev`. No flag drift between CI and the
+#      npm script.
 #   3. Upload `walkthrough/` as the Pages artifact.
 #   4. Deploy via actions/deploy-pages.
 
@@ -68,12 +68,8 @@ jobs:
       - name: Init meander submodule
         run: git submodule update --init --depth=1 upstream/meander
 
-      - name: Generate walkthrough (minified, base-path=/socket-packageurl-js)
-        run: >
-          pnpm walkthrough
-          --minify
-          --base-path=/socket-packageurl-js
-          generate walkthrough.json
+      - name: Generate walkthrough (auto-prod via CI env)
+        run: pnpm walkthrough:build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0

.github/workflows/deploy-val.yml .github/workflows/valtown.yml.github/workflows/deploy-val.yml renamed to .github/workflows/valtown.yml

@@ -35,7 +35,7 @@ on:
       - 'val/**'
       - 'scripts/walkthrough.mts'
       - 'scripts/audit-deps.mts'
-      - '.github/workflows/deploy-val.yml'
+      - '.github/workflows/valtown.yml'
       - 'package.json'
       - 'pnpm-lock.yaml'
   workflow_dispatch:
@@ -46,7 +46,7 @@ permissions:
 # Queue deploys serially. Never cancel a running deploy — a partial
 # upload can leave Val Town with a mix of old + new file versions.
 concurrency:
-  group: deploy-val
+  group: valtown
   cancel-in-progress: false
 
 jobs:
@@ -68,7 +68,7 @@ jobs:
         run: |
           if [ -z "$VALTOWN_TOKEN" ]; then
             echo "::error::VALTOWN_TOKEN secret is not configured."
-            echo "::error::See .github/workflows/deploy-val.yml header for setup steps."
+            echo "::error::See .github/workflows/valtown.yml header for setup steps."
             exit 1
           fi
           echo "VALTOWN_TOKEN present (length: ${#VALTOWN_TOKEN})"
@@ -79,8 +79,8 @@ jobs:
           checkout-fetch-depth: '1'
 
       - name: Deploy val
-        # `pnpm walkthrough deploy-val` runs the Socket.dev malware
+        # `pnpm walkthrough valtown` runs the Socket.dev malware
         # audit on the val's transitive closure first — a finding
         # fails fast before any upload. Deploy receipt (file + sha256)
         # prints to GITHUB_STEP_SUMMARY at the end.
-        run: pnpm walkthrough deploy-val
+        run: pnpm walkthrough valtown

package.json

@@ -63,10 +63,9 @@
     "update:data:npm": "node scripts/update-data-npm.mts",
     "walkthrough": "node scripts/walkthrough.mts",
     "walkthrough:build": "node scripts/walkthrough.mts generate walkthrough.json",
-    "walkthrough:build:prod": "node scripts/walkthrough.mts --minify --base-path=/socket-packageurl-js generate walkthrough.json",
     "walkthrough:serve": "node scripts/walkthrough.mts serve",
     "walkthrough:watch": "node scripts/walkthrough.mts watch walkthrough.json",
-    "walkthrough:val": "node scripts/walkthrough.mts deploy-val"
+    "walkthrough:valtown": "node scripts/walkthrough.mts valtown"
   },
   "devDependencies": {
     "@anthropic-ai/claude-code": "2.1.92",

scripts/walkthrough.mts

@@ -1008,24 +1008,91 @@ const failWith =
     process.exit(1)
   }
 
+// Preset shorthand — sets minify + base-path in one flag.
+//   --prod  ≈  --minify --base-path=/socket-packageurl-js (GH Pages layout)
+//   --dev   ≈  plain, no minify, no base-path (local-friendly)
+// Explicit --minify / --base-path= still work and override the preset.
+// No preset given? Auto-pick based on `CI` in process.env:
+//   CI set (GitHub Actions, GitLab, etc.) → prod
+//   CI unset (local machine)              → dev
+const PROD_BASE_PATH = '/socket-packageurl-js'
+
 function main(): void {
   const args = process.argv.slice(2)
   const refresh = args.includes('--refresh')
-  const minify = args.includes('--minify')
-  // Parse --base-path=<p>. When set, every root-relative asset URL
-  // and Val-Town-shaped part link is rewritten so the output works
-  // under a subdirectory host (e.g. GitHub Pages /<repo>/). Leading
-  // slash enforced, trailing slash stripped so path joins are clean.
+
+  // Explicit flags.
+  const wantDev = args.includes('--dev')
+  const wantProd = args.includes('--prod')
+  const explicitMinify = args.includes('--minify')
   const basePathArg = args.find(a => a.startsWith('--base-path='))
-  const basePath = basePathArg
+  const explicitBasePath = basePathArg
     ? normalizeBasePath(basePathArg.slice('--base-path='.length))
-    : ''
+    : undefined
+
+  // Resolve preset. Explicit --dev / --prod wins; otherwise CI env var
+  // picks prod. `'CI' in process.env` covers any CI that exports it
+  // (GitHub Actions, GitLab CI, CircleCI, most).
+  const preset: 'dev' | 'prod' = wantProd
+    ? 'prod'
+    : wantDev
+      ? 'dev'
+      : 'CI' in process.env
+        ? 'prod'
+        : 'dev'
+
+  // Final knobs — explicit flag beats preset default.
+  const minify = explicitMinify || preset === 'prod'
+  const basePath =
+    explicitBasePath !== undefined
+      ? explicitBasePath
+      : preset === 'prod'
+        ? PROD_BASE_PATH
+        : ''
+
   const rest = args.filter(
-    a => a !== '--refresh' && a !== '--minify' && !a.startsWith('--base-path='),
+    a =>
+      a !== '--refresh' &&
+      a !== '--minify' &&
+      a !== '--dev' &&
+      a !== '--prod' &&
+      !a.startsWith('--base-path='),
   )
   const command = rest[0]
 
+  const HELP_TEXT = [
+    'pnpm walkthrough — walkthrough generator for the Socket pilot',
+    '',
+    'Subcommands:',
+    '  generate <walkthrough.json>   Build the walkthrough HTML/CSS/JS.',
+    '  serve [--port=8080]           Start the local dev server.',
+    '  watch <walkthrough.json>      Build + serve + rebuild on source change.',
+    '  valtown [--name=<valname>]    Deploy val/ to Val Town.',
+    '  token <set|clear|status>      Manage the Val Town API token.',
+    '  doctor                        Check external-tool prerequisites.',
+    '',
+    'Presets (apply to build/serve/watch):',
+    '  --dev    Local-friendly: no minify, no base-path.',
+    `  --prod   GH Pages-shaped: --minify + --base-path=${PROD_BASE_PATH}.`,
+    '  Default: `prod` when the `CI` env var is set, else `dev`.',
+    '',
+    'Explicit knobs (override presets piecewise):',
+    '  --minify                 Minify emitted JS/CSS.',
+    '  --base-path=/prefix      Subdir URL prefix for assets + part links.',
+    '  --refresh                Force-rebuild the meander submodule.',
+    '',
+    'Show this help: pnpm walkthrough --help  (or -h)',
+  ].join('\n')
+
   switch (command) {
+    case undefined:
+    case '--help':
+    case '-h':
+      // POSIX convention: --help is a successful request. Stdout, exit 0 —
+      // so `pnpm walkthrough --help > help.txt` works and shell checks
+      // can detect availability by capturing stdout.
+      console.log(HELP_TEXT)
+      return
     case 'generate':
       generate(refresh, minify, basePath, rest.slice(1)).catch(
         failWith('generate'),
@@ -1037,8 +1104,8 @@ function main(): void {
     case 'watch':
       watch(refresh, minify, basePath, rest.slice(1)).catch(failWith('watch'))
       break
-    case 'deploy-val':
-      deployVal(rest.slice(1)).catch(failWith('deploy-val'))
+    case 'valtown':
+      deployValtown(rest.slice(1)).catch(failWith('valtown'))
       break
     case 'token':
       tokenCli(rest.slice(1)).catch(failWith('token'))
@@ -1047,14 +1114,10 @@ function main(): void {
       doctor().catch(failWith('doctor'))
       break
     default:
+      // Unknown command — stderr + non-zero exit, with a pointer to
+      // --help rather than dumping the full usage block here.
       console.error(
-        'Usage:\n' +
-          '  pnpm walkthrough [--refresh] [--minify] [--base-path=/prefix] generate <walkthrough.json>\n' +
-          '  pnpm walkthrough [--base-path=/prefix] serve [--port=8080]\n' +
-          '  pnpm walkthrough [--minify] [--base-path=/prefix] watch <walkthrough.json>\n' +
-          '  pnpm walkthrough deploy-val [--name=<valname>]\n' +
-          '  pnpm walkthrough token <set|clear|status>\n' +
-          '  pnpm walkthrough doctor',
+        `Unknown command: ${command}\n\nRun \`pnpm walkthrough --help\` for usage.`,
       )
       process.exit(1)
   }
@@ -1119,14 +1182,14 @@ function printDeployReceipt(
       appendFileSync(summaryPath, summary + '\n')
     } catch (err) {
       console.warn(
-        '[deploy-val] could not write GITHUB_STEP_SUMMARY:',
+        '[valtown] could not write GITHUB_STEP_SUMMARY:',
         (err as Error).message,
       )
     }
   }
 }
 
-async function deployVal(args: readonly string[]): Promise<void> {
+async function deployValtown(args: readonly string[]): Promise<void> {
   const envFile = path.join(repoRoot, '.env.local')
   if (existsSync(envFile)) {
     loadDotEnv(envFile)