@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/validate-command-router.cjs

@@ -47,7 +47,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
             // context: CJS-only — complex inline logic using classifyContextUtilization
             // with custom output formatting that has no direct SDK counterpart.
             context: () => {
-                const opts = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tokens-used', 'context-window']);
+                const opts = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['tokens-used', 'context-window'], booleanFlags: ['json'], positionals: 2 }, error);
                 if (opts['tokens-used'] === null) {
                     error('--tokens-used <integer> is required for `validate context`');
                     return;
@@ -73,7 +73,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
                     return;
                 }
                 const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
-                if (args.includes('--json')) {
+                if (opts['json'] === true) {
                     outputFn(result, raw);
                 }
                 else {

package/gsd-core/bin/lib/validate.cjs

@@ -40,24 +40,37 @@ exports.buildNotStartedPhaseVariants = buildNotStartedPhaseVariants;
 exports.textEncodingError = textEncodingError;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
+const { OPTIONAL_PROJECT_CODE_PREFIX_SOURCE, 
+// #2528 review: taken from the owner rather than derived here by
+// `replaceAll('A-Z', 'A-Za-z')` — that derivation silently no-ops (and narrows
+// this module to uppercase-only) the day phase-id.cts renders the class any
+// other way. See the constants' doc comment in phase-id.cts.
+CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE, CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE, PHASE_CONTINUATION_SEGMENT_SOURCE, } = phaseIdMod;
 // ── Issue #26: regex constants (W005, W006-archived) ────────────────────────
 // Matches legacy numeric dirs (01-setup), milestone-prefixed dirs (02-01-setup),
 // deep dirs (02-04-01-deep), and project-code-prefixed variants (GSD-02-01-setup).
 exports.phaseDirNameRe = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}\\d{2,}(?:-\\d+)*(?:\\.\\d+)*-[\\w-]+$`, 'i');
-// Extracts the full phase token from a directory name, including milestone-prefixed
-// multi-segment tokens like "02-01" from "02-01-setup" or "GSD-02-01-setup".
+// Extracts the full phase token from a directory name, including project-code and
+// milestone prefixes plus multi-segment tokens like "02-01" from "02-01-setup"
+// or "GSD-02-01" from "GSD-02-01-setup". The capture intentionally matches
+// extractPhaseToken() exactly; health-validation consumers strip the project code
+// only where their historical disk/roadmap comparison requires a numeric token.
 // #2043: a *continuation* sub-phase segment must be zero-padded, so a
 // single-digit slug word after a phase number (e.g. "46-6-rs-…", slug "6 Rs …") is
 // NOT absorbed — it captures "46", not "46-6". #2232: the continuation width is
 // exactly 2 (PHASE_CONTINUATION_SEGMENT_SOURCE), so a ≥3-digit slug word (a year:
 // "14-2026-photos-…") is not absorbed either — it captures "14", not "14-2026".
-// The first component stays "\d+"
+// #2528: this regex stays the LITERAL reading of the name and does NOT try to
+// re-classify an absorbed 2-digit continuation as a slug word — see the
+// extractPhaseToken doc comment for why that is a resolution-layer job
+// (matchPhaseDirs), not a tokenizer one. The two surfaces must agree, and they
+// agree on the literal reading. The first component stays "\d+"
 // (with the "[A-Z]?" suffix) so single-digit letter-suffixed phase ids ("1A") and
 // milestone-prefixed single-digit sub-phases ("M1-2" → prefix "M1-" stripped, then
 // "2") still match. The trailing boundary "(?:-|$)" (was "(?:-[a-z]|$)") lets a slug
 // that starts with a digit terminate the token.
-exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^${OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}(\\d+(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE})*[A-Z]?(?:\\.\\d+)*)(?:-|$)`, 'i');
+exports.PHASE_TOKEN_FROM_DIR_RE = new RegExp(`^(${CASE_FLEXIBLE_PROJECT_CODE_PREFIX_SOURCE}` +
+    `\\d+[A-Za-z]?(?:-${PHASE_CONTINUATION_SEGMENT_SOURCE}[A-Z]?)*(?:\\.\\d+)*)(?:-|$)`);
 exports.MILESTONE_ARCHIVE_DIR_RE = /^v\d+.*-phases$/i;
 // ── Issue #26: I001 canonicalization ────────────────────────────────────────
 function canonicalPlanStem(stem) {
@@ -65,7 +78,8 @@ function canonicalPlanStem(stem) {
     // so a digit-leading slug word (e.g. "46-6-rs-…") is not mistaken
     // for a "46-6" phase/plan pair. #2232: exactly 2 digits, so a year-leading
     // slug ("14-2026-photos-…") is not mistaken for a "14-2026" pair either.
-    const m = stem.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})`, 'i'));
+    const m = stem.match(new RegExp(`^(${CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE}-${PHASE_CONTINUATION_SEGMENT_SOURCE})` +
+        `(?=[A-Z](?:-|$)|-|$)`));
     return m ? m[1] : stem;
 }
 // ── Issue #6: phase variant helpers (W006/W007) ──────────────────────────────

package/gsd-core/bin/lib/vendor/README.md

@@ -0,0 +1,75 @@
+# vendor/
+
+This directory holds **verbatim, unmodified** copies of third-party build
+artifacts that `gsd-core/bin/**` needs at runtime.
+
+## Why
+
+`gsd-core/bin/**` is copied by the installer into trees that have **no
+`node_modules`** (e.g. `~/.claude/gsd-core/`). Any external (non-relative,
+non-builtin) `require()`/`import` under `gsd-core/bin/**` breaks `verify`
+(and everything else) for every installed user, because the module simply
+cannot be resolved there. The fix is to vendor the compiled artifact
+in-tree instead of depending on it being installed as an npm package.
+`eslint-rules/no-external-require-in-bin.cjs` enforces this at lint time.
+
+## Contents
+
+- `re2js.cjs` — verbatim copy of `node_modules/re2js/build/index.cjs`
+  (upstream package `re2js`, pinned version see `package.json`
+  `devDependencies.re2js`). Used by `src/pattern.cts` (compiled to
+  `gsd-core/bin/lib/pattern.cjs`) for linear-time RE2 pattern compilation.
+- `re2js.d.cts` — verbatim copy of `node_modules/re2js/build/index.d.cts`,
+  so TypeScript resolves types for the relative import from `src/pattern.cts`.
+- `js-yaml.cjs` — verbatim copy of `node_modules/js-yaml/dist/js-yaml.js`
+  (upstream package `js-yaml`, pinned version see `package.json`
+  `devDependencies.js-yaml`). ADR-3473 §8.1 (#3881): the single YAML parser
+  this repo standardizes on. The `dist` UMD bundle is the vendorable
+  artifact — js-yaml's `exports.require` entry (`index.js`) is *not*
+  self-contained; `dist/js-yaml.js` loads under `require()`, contains zero
+  `require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
+  `YAMLException`.
+
+## Two kinds of type twin
+
+Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
+resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
+(module resolution for a `.cts` source is relative to `src/`, not the
+compiled output dir). There are two kinds:
+
+- **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
+  upstream `.d.cts`/`.d.ts` that ships with the package. Both the
+  `gsd-core/bin/lib/vendor/` copy and the `src/vendor/` copy are checked by
+  `scripts/lint-vendored-deps.cjs` against `node_modules` and against each
+  other.
+- **hand-authored** (`js-yaml.d.cts`) — js-yaml ships **no** type
+  declarations upstream and `@types/js-yaml` is not installed, so there is
+  nothing to copy verbatim. `src/vendor/js-yaml.d.cts` is written by hand,
+  declares only the symbols actually used (`load`, `dump`,
+  `FAILSAFE_SCHEMA`, `YAMLException`), and is **excluded** from
+  `lint-vendored-deps.cjs`'s byte-compare — there is no upstream file to
+  compare it against. The narrowness is deliberate: anchors, aliases,
+  custom types and `loadAll` are unreachable from typed code, which is a
+  compile-time enforcement of ADR-3473 §8.1's refusal to expand them.
+
+## Do not hand-edit
+
+These files are **verbatim** copies of upstream build output. Never edit
+them directly — refresh them from `node_modules` instead:
+
+```
+cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
+cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts
+cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts
+
+cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
+# js-yaml.d.cts has no upstream counterpart — update src/vendor/js-yaml.d.cts
+# by hand if the js-yaml API surface this repo depends on changes.
+```
+
+`node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
+byte-for-byte from its `node_modules` upstream, from its own source-side
+type twin (upstream-verbatim twins only), or from the version pinned in
+`package.json` `devDependencies`. It is table-driven (`VENDORED` in that
+script) — adding a third vendored package means adding a row, not a second
+hardcoded check block (ADR-3473 §8.3, "one implementation per rule").