@dzhechkov/harness-cli 0.7.3 → 0.7.5

package/src/install-spec.ts

@@ -0,0 +1,86 @@
+/**
+ * `dz install` argument resolution — feature install-spec-honesty (backlog 43a52cf2 + c999786b).
+ *
+ * cmdInstall used to splice the RAW argument into `join(projectRoot, 'node_modules', pkg)`.
+ * MEASURED, five broken forms: an absolute path (path.join CONCATENATES an absolute segment —
+ * `/proj/node_modules/home/dz/pkgs/...`); a versioned spec `@dzhechkov/health-advisor@1.9.0`
+ * (the WORST: `npm install` SUCCEEDS and mutates the project's package.json, then dz dies on an
+ * invented path with exit 1 — and the versioned form is exactly what the npm-lag README
+ * prescribes); a tarball `pack-1.0.0.tgz`; `github:user/repo`; an alias `ha@npm:...`.
+ *
+ * The cure is a PURE resolver that runs BEFORE any npm process: every accepted form yields the
+ * npm spec AND the node_modules directory name it will land under; everything else is a NAMED
+ * refusal carrying the working two-command form. A spec whose landing dir cannot be established
+ * must never reach npm — that is what made the versioned failure mutate state and then die.
+ */
+
+export interface InstallSpecProbe {
+  /** Does `path` exist as a regular file? */
+  readonly isFile: (path: string) => boolean;
+  /** Does `path` exist as a directory? */
+  readonly isDir: (path: string) => boolean;
+  /** `name` from `package/package.json` inside a tarball, or null (unreadable/absent). */
+  readonly readTarballName: (path: string) => string | null;
+  /** `name` from `<dir>/package.json`, or null. */
+  readonly readDirName: (path: string) => string | null;
+}
+
+export type InstallSpecResolution =
+  | { readonly kind: 'name' | 'versioned' | 'alias' | 'tarball' | 'dir'; readonly npmSpec: string; readonly dirName: string }
+  | { readonly kind: 'refused'; readonly reason: string; readonly hint: string };
+
+const BARE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+/** The two-command fallback that always works, named in every refusal (43a52cf2's own ask). */
+function twoCommandHint(raw: string): string {
+  return `working form: npm install ${raw} --save-dev && dz init --skills-dir node_modules/<installed-package-name>`;
+}
+
+export function resolveInstallSpec(raw: string, resolveAgainstCwd: (p: string) => string, probe: InstallSpecProbe): InstallSpecResolution {
+  const spec = raw.trim();
+  if (spec === '') return { kind: 'refused', reason: 'empty spec', hint: 'dz install <package|package@version|path/to.tgz|path/to/dir>' };
+
+  // Path forms first — a path is never an npm name. Absolute, explicit-relative, or an existing
+  // .tgz/.tar.gz/.dir anywhere: the OLD code spliced these into node_modules verbatim.
+  const looksPathy = spec.startsWith('/') || spec.startsWith('./') || spec.startsWith('../') || /\.(tgz|tar\.gz)$/.test(spec);
+  if (looksPathy) {
+    const abs = resolveAgainstCwd(spec);
+    if (/\.(tgz|tar\.gz)$/.test(spec)) {
+      if (!probe.isFile(abs)) return { kind: 'refused', reason: `tarball not found: ${abs}`, hint: twoCommandHint(spec) };
+      const name = probe.readTarballName(abs);
+      if (name === null) return { kind: 'refused', reason: `cannot read package/package.json name from ${abs}`, hint: twoCommandHint(spec) };
+      return { kind: 'tarball', npmSpec: abs, dirName: name };
+    }
+    if (probe.isDir(abs)) {
+      const name = probe.readDirName(abs);
+      if (name === null) return { kind: 'refused', reason: `${abs} has no readable package.json name`, hint: twoCommandHint(spec) };
+      return { kind: 'dir', npmSpec: abs, dirName: name };
+    }
+    return { kind: 'refused', reason: `path does not exist: ${abs}`, hint: twoCommandHint(spec) };
+  }
+
+  // git/github/url specs: the landing dir is not cheaply establishable — refuse with the cure.
+  if (/^(github:|git\+|git:|https?:\/\/)/.test(spec)) {
+    return { kind: 'refused', reason: `git/url specs are not resolvable to a node_modules dir up front (${spec})`, hint: twoCommandHint(spec) };
+  }
+
+  // alias@npm:real[@version] — installs under the ALIAS name.
+  const alias = /^([^@][^@]*|@[^/]+\/[^@]+)@npm:(.+)$/.exec(spec);
+  if (alias !== null) {
+    return { kind: 'alias', npmSpec: spec, dirName: alias[1] as string };
+  }
+
+  if (BARE_NAME_RE.test(spec)) return { kind: 'name', npmSpec: spec, dirName: spec };
+
+  // name@version / @scope/name@version — the dir is the name WITHOUT the version.
+  const at = spec.lastIndexOf('@');
+  if (at > 0) {
+    const name = spec.slice(0, at);
+    const version = spec.slice(at + 1);
+    if (BARE_NAME_RE.test(name) && version !== '' && !version.includes('/')) {
+      return { kind: 'versioned', npmSpec: spec, dirName: name };
+    }
+  }
+
+  return { kind: 'refused', reason: `unrecognized install spec: ${spec}`, hint: twoCommandHint(spec) };
+}

package/src/known-flags.ts

@@ -0,0 +1,291 @@
+/**
+ * Every `--name` this CLI knows: the union of every name its code READS and every name its help
+ * DOCUMENTS. GENERATED — `test/known-flags-drift.test.ts` re-derives it from `cli.ts` and fails if
+ * this list has gone stale, so a new flag cannot silently start warning at its own users.
+ *
+ * It is deliberately a FLAT set, not a per-command map. Both ways of building a per-command list
+ * were measured and both are unsafe: 53 of the names the CLI reads appear nowhere in help, and
+ * static extraction over the dispatch table lost `--week` from `dz recap` while picking up a
+ * neighbour's flags for `dz usage`. A refusal built on either would reject working commands.
+ * See harness-core/src/cli-flag-notice.ts for the full reasoning and the honest limit.
+ */
+export const KNOWN_CLI_FLAGS: readonly string[] = [
+  'affected',
+  'all',
+  'allow-same-family',
+  'allow-same-family-qe',
+  'any',
+  'append',
+  'apply',
+  'arg',
+  'artifact',
+  'at',
+  'audit-dev',
+  'author',
+  'auto',
+  'base',
+  'baseline',
+  'body',
+  'book',
+  'books',
+  'bto',
+  'budget',
+  'budget-extra',
+  'bump-only',
+  'by-stage',
+  'calibrate',
+  'candidate',
+  'candidates',
+  'canonical',
+  'category',
+  'channel',
+  'check',
+  'claim-check',
+  'claude-bin',
+  'cmd',
+  'coder-family',
+  'codex-home',
+  'command',
+  'commands',
+  'commit',
+  'compare',
+  'confirm',
+  'confirmed',
+  'context-only',
+  'corroborate',
+  'count-project',
+  'day',
+  'deep',
+  'default-family',
+  'desc',
+  'description',
+  'diff',
+  'diff-filter',
+  'dir',
+  'domain',
+  'done',
+  'draft',
+  'dry-run',
+  'effect',
+  'effort',
+  'emit',
+  'emit-policy',
+  'enrich',
+  'epsilon',
+  'expect',
+  'expect-commands',
+  'export',
+  'fa-record',
+  'fail-on',
+  'fail-on-undergrant',
+  'family',
+  'feature-dir',
+  'files',
+  'filter',
+  'finalize',
+  'findings',
+  'flag',
+  'force',
+  'forget',
+  'format',
+  'from',
+  'from-',
+  'from-json',
+  'from-kus',
+  'from-pack',
+  'from-slice',
+  'from-spec',
+  'full',
+  'gates',
+  'gen-critic',
+  'goal',
+  'guard',
+  'guards',
+  'half-year',
+  'harmonize',
+  'help',
+  'holdout',
+  'html',
+  'id',
+  'include-domain',
+  'include-pairs',
+  'init',
+  'input-hash',
+  'install',
+  'install-driver',
+  'install-hook',
+  'into',
+  'invariants',
+  'json',
+  'judge',
+  'k',
+  'keep-scratch',
+  'key',
+  'kind',
+  'ladder',
+  'legacy',
+  'lexical',
+  'license',
+  'limit',
+  'list',
+  'live-content',
+  'loc-cap',
+  'local-path',
+  'manifest',
+  'margin',
+  'mark',
+  'max',
+  'max-wall-clock',
+  'memory',
+  'mock',
+  'mode',
+  'model',
+  'module',
+  'month',
+  'n',
+  'name',
+  'name-only',
+  'night',
+  'no-audit',
+  'no-decorate',
+  'no-dry-run',
+  'no-evals',
+  'no-filters',
+  'no-fund',
+  'no-guard',
+  'no-hooks',
+  'no-index',
+  'no-issue',
+  'no-memory',
+  'no-merges',
+  'no-mirror',
+  'no-provenance',
+  'no-result',
+  'no-semantic',
+  'no-session-persistence',
+  'no-teach',
+  'no-verify',
+  'o',
+  'once',
+  'oneline',
+  'only',
+  'op',
+  'original',
+  'out',
+  'output',
+  'output-format',
+  'override',
+  'pack',
+  'pack-destination',
+  'package',
+  'pair',
+  'pattern',
+  'periods',
+  'pick',
+  'plan',
+  'plugin-dir',
+  'porcelain',
+  'preset',
+  'pretty',
+  'preview',
+  'project',
+  'promote',
+  'proposal',
+  'provenance',
+  'prune-noise',
+  'prune-quarantine',
+  'pubkey',
+  'publish',
+  'quarter',
+  'reason',
+  'rebaseline',
+  'recalled',
+  'reconcile',
+  'record-provisional',
+  'refresh-publishes',
+  'registry',
+  'reinforce',
+  'remove',
+  'report',
+  'require-plan',
+  'require-signing',
+  'rerank',
+  'result',
+  'resume',
+  'revise',
+  'reward',
+  'row',
+  'run',
+  'run-dir',
+  'run-id',
+  'runner',
+  'safe-mode',
+  'sandbox',
+  'save-dev',
+  'scenarios',
+  'scope-check',
+  'score',
+  'seed',
+  'select',
+  'semantic',
+  'send',
+  'session',
+  'sessions-dir',
+  'short',
+  'show-toplevel',
+  'sign-key',
+  'since',
+  'skill',
+  'skills-dir',
+  'slice',
+  'slug',
+  'source',
+  'split',
+  'stage',
+  'stage-timeout',
+  'stages-json',
+  'static',
+  'stats',
+  'status',
+  'stdin',
+  'step',
+  'stored',
+  'strict',
+  'strict-mcp-config',
+  'subsystem',
+  'success',
+  'tag',
+  'target',
+  'task',
+  'teach',
+  'test',
+  'test-cmd',
+  'text',
+  'threshold',
+  'tie-rate',
+  'tier',
+  'timeout',
+  'title',
+  'tolerance',
+  'tools',
+  'topics',
+  'type',
+  'usage',
+  'validate',
+  'verbose',
+  'verified',
+  'verify',
+  'version',
+  'wall-clock-extra',
+  'weak',
+  'week',
+  'weekly',
+  'window-days',
+  'window',
+  'with-pairs',
+  'with-references',
+  'work-order',
+  'write',
+  'year',
+  'yes',
+];