@dzhechkov/harness-core 0.4.5 → 0.5.1

package/dist/shell-veto-policy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shell veto policy (`crossrt-2-codex-hooks`, ADR-004 + ADR-005).
+ *
+ * ONE rule, judged on the raw command string, with no I/O of any kind. The mode — what the CALLER
+ * does with a hit — is decided by the caller from project config, never here.
+ *
+ * Polarity, in one sentence (ADR-004): **a policy hit ⇒ WARN by default, BLOCK only when the
+ * project opted in; our own failure ⇒ always ALLOW.**
+ *
+ * ## Why exactly one rule, and why this one
+ *
+ * `shell-veto-policy.ts` is NOT a general shell-guardrail engine (plan §0.1's C4 fence). Its
+ * charter is a single rule whose violation is **unambiguous**: the command line explicitly asks for
+ * WEAKER authentication than the ssh default. Every token below is one a safe invocation never
+ * contains, so a hit always means the user deliberately disabled a protection.
+ *
+ * The withdrawn v1 (`ssh-no-identity`, AM-23) judged the ABSENCE of `-i`/`IdentityFile=`, which
+ * blocked `ssh myhost` whenever the identity came from `~/.ssh/config` or `ssh-agent` — the normal
+ * secure case — from a user-global registry that reaches every directory on the machine. Absence of
+ * a token is not evidence of intent; presence of these four is.
+ *
+ * `StrictHostKeyChecking=no` and `UserKnownHostsFile=/dev/null` are deliberately NOT rules: they are
+ * a real weakening, but CI images use them legitimately, so no unambiguous verdict is available.
+ * They are the first candidates for a future rule with its own ADR — **no second rule ships in this
+ * leg**.
+ *
+ * @packageDocumentation
+ */
+/** What the caller does with a hit. `warn` is the shipped default (ADR-004). */
+export type VetoMode = 'off' | 'warn' | 'block';
+/** A policy hit. `null` from {@link vetoShellCommand} means allow. */
+export interface VetoHit {
+    readonly rule: string;
+    readonly reason: string;
+}
+/** The one rule id this leg ships. Exported so tests and the probe cannot drift from it. */
+export declare const SHELL_VETO_RULE_ID = "ssh-explicit-auth-weakening";
+/**
+ * Judge one raw shell command.
+ *
+ * @returns a {@link VetoHit} when the command EXPLICITLY weakens ssh authentication, else `null`.
+ *          Pure: no filesystem, no environment, no config, no clock.
+ */
+export declare function vetoShellCommand(command: string): VetoHit | null;
+/**
+ * Resolve the enforcement mode from a parsed `.dz/config.json`.
+ *
+ * ABSENT, unknown, non-string, or malformed ⇒ `'warn'`. Never `'block'` by default: fail-closed is
+ * a decision the owner makes, not one a user-global hook install imposes on every directory
+ * (ADR-004 / AM-24). A mutant that flips this default is registered in the mutation registry.
+ */
+export declare function resolveVetoMode(projectConfig: unknown): VetoMode;
+//# sourceMappingURL=shell-veto-policy.d.ts.map

package/dist/shell-veto-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-veto-policy.d.ts","sourceRoot":"","sources":["../src/shell-veto-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gFAAgF;AAChF,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AA6BhE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA4BhE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,OAAO,GAAG,QAAQ,CAOhE"}

package/dist/shell-veto-policy.js

@@ -0,0 +1,103 @@
+/**
+ * Shell veto policy (`crossrt-2-codex-hooks`, ADR-004 + ADR-005).
+ *
+ * ONE rule, judged on the raw command string, with no I/O of any kind. The mode — what the CALLER
+ * does with a hit — is decided by the caller from project config, never here.
+ *
+ * Polarity, in one sentence (ADR-004): **a policy hit ⇒ WARN by default, BLOCK only when the
+ * project opted in; our own failure ⇒ always ALLOW.**
+ *
+ * ## Why exactly one rule, and why this one
+ *
+ * `shell-veto-policy.ts` is NOT a general shell-guardrail engine (plan §0.1's C4 fence). Its
+ * charter is a single rule whose violation is **unambiguous**: the command line explicitly asks for
+ * WEAKER authentication than the ssh default. Every token below is one a safe invocation never
+ * contains, so a hit always means the user deliberately disabled a protection.
+ *
+ * The withdrawn v1 (`ssh-no-identity`, AM-23) judged the ABSENCE of `-i`/`IdentityFile=`, which
+ * blocked `ssh myhost` whenever the identity came from `~/.ssh/config` or `ssh-agent` — the normal
+ * secure case — from a user-global registry that reaches every directory on the machine. Absence of
+ * a token is not evidence of intent; presence of these four is.
+ *
+ * `StrictHostKeyChecking=no` and `UserKnownHostsFile=/dev/null` are deliberately NOT rules: they are
+ * a real weakening, but CI images use them legitimately, so no unambiguous verdict is available.
+ * They are the first candidates for a future rule with its own ADR — **no second rule ships in this
+ * leg**.
+ *
+ * @packageDocumentation
+ */
+/** The one rule id this leg ships. Exported so tests and the probe cannot drift from it. */
+export const SHELL_VETO_RULE_ID = 'ssh-explicit-auth-weakening';
+/**
+ * Shell word boundaries. Both ends of every token are anchored, so `echo "sshpassword"` and
+ * `--my-passwordauthentication=yes` cannot hit: a user-global guard that matches on a bare
+ * substring is one common word away from a machine-wide outage.
+ */
+const BOUNDARY = String.raw `[\s;&|()'"\`]`;
+const OPT = String.raw `(?:^|${BOUNDARY})-o\s*`;
+const END = String.raw `(?=$|${BOUNDARY})`;
+/** `-o PasswordAuthentication=yes` — the user turns ON password auth against the ssh default. */
+const PASSWORD_AUTHENTICATION = new RegExp(`${OPT}passwordauthentication\\s*=\\s*yes${END}`, 'i');
+/** `-o PubkeyAuthentication=no` — the user turns OFF key auth. */
+const PUBKEY_AUTHENTICATION = new RegExp(`${OPT}pubkeyauthentication\\s*=\\s*no${END}`, 'i');
+/** `-o PreferredAuthentications=…password…` — the user ORDERS password auth ahead of pubkey. */
+const PREFERRED_AUTHENTICATIONS = new RegExp(`${OPT}preferredauthentications\\s*=\\s*` +
+    `(?:[a-z][a-z0-9-]*\\s*,\\s*)*` +
+    `(?:password|keyboard-interactive)` +
+    `(?:\\s*,\\s*[a-z][a-z0-9-]*)*${END}`, 'i');
+/** `sshpass` as a COMMAND TOKEN — a password is fed to ssh from the command line by construction. */
+const SSHPASS_TOKEN = new RegExp(`(?:^|${BOUNDARY})sshpass${END}`, 'i');
+/**
+ * Judge one raw shell command.
+ *
+ * @returns a {@link VetoHit} when the command EXPLICITLY weakens ssh authentication, else `null`.
+ *          Pure: no filesystem, no environment, no config, no clock.
+ */
+export function vetoShellCommand(command) {
+    if (typeof command !== 'string' || command === '')
+        return null;
+    if (SSHPASS_TOKEN.test(command)) {
+        return {
+            rule: SHELL_VETO_RULE_ID,
+            reason: 'sshpass feeds an ssh password from the command line, disabling key-based auth by construction',
+        };
+    }
+    if (PASSWORD_AUTHENTICATION.test(command)) {
+        return {
+            rule: SHELL_VETO_RULE_ID,
+            reason: 'PasswordAuthentication=yes turns ON password auth against the ssh default',
+        };
+    }
+    if (PUBKEY_AUTHENTICATION.test(command)) {
+        return {
+            rule: SHELL_VETO_RULE_ID,
+            reason: 'PubkeyAuthentication=no turns OFF key auth',
+        };
+    }
+    if (PREFERRED_AUTHENTICATIONS.test(command)) {
+        return {
+            rule: SHELL_VETO_RULE_ID,
+            reason: 'PreferredAuthentications orders password/keyboard-interactive auth ahead of pubkey',
+        };
+    }
+    return null;
+}
+/**
+ * Resolve the enforcement mode from a parsed `.dz/config.json`.
+ *
+ * ABSENT, unknown, non-string, or malformed ⇒ `'warn'`. Never `'block'` by default: fail-closed is
+ * a decision the owner makes, not one a user-global hook install imposes on every directory
+ * (ADR-004 / AM-24). A mutant that flips this default is registered in the mutation registry.
+ */
+export function resolveVetoMode(projectConfig) {
+    if (typeof projectConfig !== 'object' || projectConfig === null)
+        return 'warn';
+    const hooks = projectConfig['hooks'];
+    if (typeof hooks !== 'object' || hooks === null)
+        return 'warn';
+    const mode = hooks['shellVeto'];
+    if (mode === 'off' || mode === 'warn' || mode === 'block')
+        return mode;
+    return 'warn';
+}
+//# sourceMappingURL=shell-veto-policy.js.map

package/dist/shell-veto-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-veto-policy.js","sourceRoot":"","sources":["../src/shell-veto-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAWH,4FAA4F;AAC5F,MAAM,CAAC,MAAM,kBAAkB,GAAG,6BAA6B,CAAC;AAEhE;;;;GAIG;AACH,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAA,eAAe,CAAC;AAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAA,QAAQ,QAAQ,QAAQ,CAAC;AAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAA,QAAQ,QAAQ,GAAG,CAAC;AAE1C,iGAAiG;AACjG,MAAM,uBAAuB,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG,qCAAqC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;AAElG,kEAAkE;AAClE,MAAM,qBAAqB,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG,kCAAkC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;AAE7F,gGAAgG;AAChG,MAAM,yBAAyB,GAAG,IAAI,MAAM,CAC1C,GAAG,GAAG,mCAAmC;IACvC,+BAA+B;IAC/B,mCAAmC;IACnC,gCAAgC,GAAG,EAAE,EACvC,GAAG,CACJ,CAAC;AAEF,qGAAqG;AACrG,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,QAAQ,QAAQ,WAAW,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE/D,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,+FAA+F;SACxG,CAAC;IACJ,CAAC;IACD,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,2EAA2E;SACpF,CAAC;IACJ,CAAC;IACD,IAAI,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,4CAA4C;SACrD,CAAC;IACJ,CAAC;IACD,IAAI,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,OAAO;YACL,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,oFAAoF;SAC7F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,aAAsB;IACpD,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC/E,MAAM,KAAK,GAAI,aAAyC,CAAC,OAAO,CAAC,CAAC;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC/D,MAAM,IAAI,GAAI,KAAiC,CAAC,WAAW,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACvE,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/skills.d.ts

@@ -22,8 +22,93 @@ export interface SkillInfo {
 }
 /** Return the ids of every `<skillsDir>/<id>/SKILL.md`, sorted. */
 export declare function discoverSkillIds(skillsDir: string): string[];
-/** Discover every skill in `skillsDir`, returning id + description. */
+/**
+ * Discover every skill in `skillsDir`, returning id + description.
+ *
+ * **Throws on the first unloadable skill — deliberately, and permanently.** This is a
+ * published export; silently turning it into a skip-and-collect function would downgrade
+ * every unknown third-party consumer from fail-closed to fail-silent without their
+ * consent (an incomplete catalogue reported as complete). Callers that want a partial
+ * listing ask for one by name: {@link listSkillsDetailed}. A pinned regression test
+ * asserts this function still throws, so a future "helpful" refactor cannot quietly
+ * erase the strict variant. (feature dz-cli-defects, ADR-001 as amended by AM-6.)
+ */
 export declare function listSkills(skillsDir: string): SkillSummary[];
+/** How much of the offending file's first line is echoed back to the user. */
+export declare const SKILL_FAILURE_FIRST_LINE_MAX = 100;
+/** One skill directory that could not be loaded. Named, so a log is actionable. */
+export interface SkillLoadFailure {
+    /** The skill id (its directory name), e.g. `bto`. */
+    readonly id: string;
+    /** ABSOLUTE path to the offending `SKILL.md`. */
+    readonly path: string;
+    /** The caught error's message, verbatim — the classifier stays out of the loader. */
+    readonly reason: string;
+    /**
+     * First line of the source text, trimmed and capped at
+     * {@link SKILL_FAILURE_FIRST_LINE_MAX}; `''` when the file is unreadable. Echoing it
+     * is what turns the message into a FIX — the user sees the H1 and knows to add the
+     * frontmatter fence.
+     */
+    readonly firstLine: string;
+}
+/** A listing that separates what parsed from what did not. */
+export interface SkillListing {
+    /** Sorted by id — same order, same shape as {@link listSkills} produces today. */
+    readonly skills: readonly SkillSummary[];
+    /** Sorted by id. Empty when every skill loaded. */
+    readonly failures: readonly SkillLoadFailure[];
+}
+/**
+ * Attribute any skill-load throw to a file. Shared by every consumer
+ * (`listSkillsDetailed`, `runInit`, `runInitSingleFileMd`, `runSync`).
+ *
+ * Best-effort on the first line: an unreadable file yields `''` rather than a second
+ * throw — this helper runs on an error path and must never become one.
+ */
+export declare function describeSkillLoadFailure(skillsDir: string, id: string, error: unknown): SkillLoadFailure;
+/**
+ * Discover every skill in `skillsDir`, separating the ones that parsed from the ones
+ * that did not. One broken `SKILL.md` never hides the rest.
+ *
+ * Catch policy: **every** error per id, not only `SkillDocumentError` — an `EACCES`, a
+ * YAML syntax error and a Zod schema rejection are all equally "this one skill is
+ * unusable". The `reason` is the caught message verbatim.
+ */
+export declare function listSkillsDetailed(skillsDir: string): SkillListing;
+/**
+ * Render a `SkillLoadFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * One helper, two rendering modes, chosen by the CALLER — never by the helper sniffing
+ * the path. `dz list` / `dz sync` print absolute paths (the user can act on those);
+ * `dz install` passes `relativeTo` = the downloaded package root, because a
+ * `node_modules/**` absolute path is not something the user can act on.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export declare function formatSkillLoadFailures(failures: readonly SkillLoadFailure[], opts?: {
+    readonly relativeTo?: string;
+}): string[];
+/**
+ * One skill that LOADED cleanly but could not be compiled for, or written to, the
+ * target. The subject is the TARGET, never the source `SKILL.md`.
+ */
+export interface SkillApplyFailure {
+    /** The skill id (its directory name). */
+    readonly id: string;
+    /** The caught error's message, verbatim. */
+    readonly reason: string;
+}
+/**
+ * Render a `SkillApplyFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * Deliberately a DIFFERENT header from {@link formatSkillLoadFailures}: the two kinds
+ * point the user at two different files, and a shared header is what let a write
+ * failure masquerade as a parse failure.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export declare function formatSkillApplyFailures(failures: readonly SkillApplyFailure[]): string[];
 /** Get detailed info about a single skill without loading all assets. */
 export declare function getSkillInfo(skillsDir: string, id: string): SkillInfo | undefined;
 /**

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAElE,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAsCD,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5D;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAM5D;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAqBjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,CAoB9E"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,iBAAiB,CAAC;AAElE,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAsCD,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CAM5D;AAWD,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,GACb,gBAAgB,CAmBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAalE;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,IAAI,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,MAAM,EAAE,CAaV;AAeD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAQzF;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAqBjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,CAoB9E"}

package/dist/skills.js

@@ -52,7 +52,17 @@ export function discoverSkillIds(skillsDir) {
         .map((entry) => entry.name)
         .sort();
 }
-/** Discover every skill in `skillsDir`, returning id + description. */
+/**
+ * Discover every skill in `skillsDir`, returning id + description.
+ *
+ * **Throws on the first unloadable skill — deliberately, and permanently.** This is a
+ * published export; silently turning it into a skip-and-collect function would downgrade
+ * every unknown third-party consumer from fail-closed to fail-silent without their
+ * consent (an incomplete catalogue reported as complete). Callers that want a partial
+ * listing ask for one by name: {@link listSkillsDetailed}. A pinned regression test
+ * asserts this function still throws, so a future "helpful" refactor cannot quietly
+ * erase the strict variant. (feature dz-cli-defects, ADR-001 as amended by AM-6.)
+ */
 export function listSkills(skillsDir) {
     return discoverSkillIds(skillsDir).map((id) => {
         const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
@@ -60,6 +70,111 @@ export function listSkills(skillsDir) {
         return { id, description: frontmatter.description };
     });
 }
+// ---------------------------------------------------------------------------
+// Skip-and-collect (feature dz-cli-defects, D1)
+//
+// The parser (`@dzhechkov/core/src/skill-document.ts`) is handed only TEXT, so its
+// message can never carry a path. `describeSkillLoadFailure` is the ONE place that
+// turns a pathless throw into a named failure — every consumer calls it, so "named,
+// never anonymous" has one implementation and one test.
+// ---------------------------------------------------------------------------
+/** How much of the offending file's first line is echoed back to the user. */
+export const SKILL_FAILURE_FIRST_LINE_MAX = 100;
+/**
+ * Attribute any skill-load throw to a file. Shared by every consumer
+ * (`listSkillsDetailed`, `runInit`, `runInitSingleFileMd`, `runSync`).
+ *
+ * Best-effort on the first line: an unreadable file yields `''` rather than a second
+ * throw — this helper runs on an error path and must never become one.
+ */
+export function describeSkillLoadFailure(skillsDir, id, error) {
+    const path = join(skillsDir, id, 'SKILL.md');
+    let firstLine = '';
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const line = (raw.split('\n', 1)[0] ?? '').replace(/\r$/, '').trim();
+        firstLine =
+            line.length > SKILL_FAILURE_FIRST_LINE_MAX
+                ? `${line.slice(0, SKILL_FAILURE_FIRST_LINE_MAX)}…`
+                : line;
+    }
+    catch {
+        firstLine = '';
+    }
+    return {
+        id,
+        path,
+        reason: error instanceof Error ? error.message : String(error),
+        firstLine,
+    };
+}
+/**
+ * Discover every skill in `skillsDir`, separating the ones that parsed from the ones
+ * that did not. One broken `SKILL.md` never hides the rest.
+ *
+ * Catch policy: **every** error per id, not only `SkillDocumentError` — an `EACCES`, a
+ * YAML syntax error and a Zod schema rejection are all equally "this one skill is
+ * unusable". The `reason` is the caught message verbatim.
+ */
+export function listSkillsDetailed(skillsDir) {
+    const skills = [];
+    const failures = [];
+    for (const id of discoverSkillIds(skillsDir)) {
+        try {
+            const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
+            const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
+            skills.push({ id, description: frontmatter.description });
+        }
+        catch (error) {
+            failures.push(describeSkillLoadFailure(skillsDir, id, error));
+        }
+    }
+    return { skills, failures };
+}
+/**
+ * Render a `SkillLoadFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * One helper, two rendering modes, chosen by the CALLER — never by the helper sniffing
+ * the path. `dz list` / `dz sync` print absolute paths (the user can act on those);
+ * `dz install` passes `relativeTo` = the downloaded package root, because a
+ * `node_modules/**` absolute path is not something the user can act on.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export function formatSkillLoadFailures(failures, opts = {}) {
+    if (failures.length === 0)
+        return [];
+    const lines = [`⚠ ${failures.length} skill(s) skipped (unparseable SKILL.md):`];
+    for (const failure of failures) {
+        const shown = opts.relativeTo !== undefined
+            ? relative(opts.relativeTo, failure.path).split('\\').join('/')
+            : failure.path;
+        lines.push(`  ${shown}`);
+        lines.push(`    ${failure.reason}`);
+        if (failure.firstLine !== '')
+            lines.push(`    (line 1: ${JSON.stringify(failure.firstLine)})`);
+    }
+    return lines;
+}
+/**
+ * Render a `SkillApplyFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * Deliberately a DIFFERENT header from {@link formatSkillLoadFailures}: the two kinds
+ * point the user at two different files, and a shared header is what let a write
+ * failure masquerade as a parse failure.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export function formatSkillApplyFailures(failures) {
+    if (failures.length === 0)
+        return [];
+    const lines = [`✗ ${failures.length} skill(s) failed to install (compile/write error):`];
+    for (const failure of failures) {
+        lines.push(`  ${failure.id}`);
+        lines.push(`    ${failure.reason}`);
+    }
+    return lines;
+}
 /** Get detailed info about a single skill without loading all assets. */
 export function getSkillInfo(skillsDir, id) {
     const skillDir = join(skillsDir, id);

package/dist/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/targets.d.ts

@@ -15,4 +15,79 @@ export declare const TARGETS: Record<TargetName, Adapter>;
 export declare const TARGET_NAMES: TargetName[];
 /** Type guard: is `value` a supported `--target` name? */
 export declare function isTargetName(value: string): value is TargetName;
+/** `TARGET_NAMES` sorted alphabetically, for display in error messages. */
+export declare const TARGET_NAMES_SORTED: readonly TargetName[];
+/**
+ * Semantic `--target` aliases — DATA, not branching logic. Adding a row is one line
+ * and zero control flow (ADR-002 §Rationale D5).
+ *
+ * Purely typographic variants (`Claude_Code`, `claudecode`, `agents.md`) are handled by
+ * normalisation, not by rows; the rows below carry only meanings normalisation cannot
+ * derive (`claude` ≠ `claude-code` by any string rule — it is an owner decision).
+ */
+export declare const TARGET_ALIASES: Readonly<Record<string, TargetName>>;
+/**
+ * Rows deleted in fix round 1 (QE F7) because they were UNREACHABLE, not because their
+ * inputs stopped working: `claude_code`, `claudecode`, `agentsmd` and `agents.md` all
+ * normalise onto a canonical name, and precedence step 2 (normalised canonical) runs
+ * BEFORE step 3 (this table). Every one of them still resolves — through normalisation,
+ * which is where the README already says typographic variants are handled.
+ *
+ * They were invisible dead data because the table test iterated every row asserting
+ * `via === 'alias'`, which is true on both paths — a PRESENCE assertion where a
+ * REACHABILITY one was intended. `target-resolution.test.ts` now removes each row from a
+ * COPY of the table and asserts the resolution changes, so a future dead row is red.
+ */
+/** The outcome of {@link resolveTargetName}. Total: every string maps to one of these. */
+export type TargetResolution = {
+    readonly kind: 'ok';
+    readonly target: TargetName;
+    readonly via: 'canonical' | 'alias';
+} | {
+    readonly kind: 'unknown';
+    readonly input: string;
+    readonly suggestion: TargetName | null;
+};
+/** Levenshtein suggestions are only offered at or below this edit distance. */
+export declare const TARGET_SUGGESTION_MAX_DISTANCE = 3;
+/**
+ * Normalise a `--target` token for matching: byte-level lowercase (never
+ * `toLocaleLowerCase` — behaviour must not vary with the host locale), trimmed, with
+ * every separator dropped so `Claude_Code`, `claude-code` and `claudecode` collapse.
+ *
+ * Exported so the alias-REACHABILITY test can ask the production normaliser whether a
+ * proposed alias row is already carried by precedence step 2, instead of keeping a
+ * second copy of this rule in the test file (fix round 1, QE F7).
+ */
+export declare function normalizeTargetToken(value: string): string;
+/**
+ * Resolve a user-supplied `--target` value to a canonical {@link TargetName}.
+ *
+ * Total, pure, no I/O. Precedence (fixed and tested):
+ *
+ * 1. exact canonical hit → `{kind:'ok', via:'canonical'}` (`isTargetName` semantics);
+ * 2. normalised canonical hit → `{kind:'ok', via:'alias'}` (`Claude_Code`, `agentsmd`);
+ * 3. explicit {@link TARGET_ALIASES} row → `{kind:'ok', via:'alias'}`;
+ * 4. unique normalised prefix → `{kind:'unknown', suggestion}`;
+ * 5. Levenshtein ≤ 3 strictly better than the runner-up → `{kind:'unknown', suggestion}`;
+ * 6. otherwise → `{kind:'unknown', suggestion:null}`.
+ *
+ * **Aliases ACCEPT; prefix and Levenshtein only SUGGEST.** An alias row is an owner
+ * decision recorded in data; a fuzzy match is a guess, and silently installing to the
+ * wrong target on a guess is worse than one round-trip.
+ */
+export declare function resolveTargetName(value: string): TargetResolution;
+/**
+ * Render the two-line failure for an unresolvable `--target`.
+ *
+ * Line 2 keeps the literal substring `--target must be one of:` — three shipped
+ * assertions (`test/cli.test.ts`) pin it, and keeping the shape additive is what makes
+ * the D3 change prove itself with NEW tests instead of rewriting old ones. The values
+ * are {@link TARGET_NAMES_SORTED} (alphabetical), which the pre-change message was not.
+ */
+export declare function formatTargetProblem(command: string, resolution: Extract<TargetResolution, {
+    kind: 'unknown';
+}>): readonly string[];
+/** The one-line diagnostic emitted (on stderr) when an alias was accepted. */
+export declare function formatTargetAliasNote(command: string, input: string, target: TargetName): string;
 //# sourceMappingURL=targets.d.ts.map

package/dist/targets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,+BAA+B;AAC/B,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAKrJ,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAa/C,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,YAAY,EAA2B,UAAU,EAAE,CAAC;AAEjE,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D"}
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,+BAA+B;AAC/B,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAKrJ,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAa/C,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,YAAY,EAA2B,UAAU,EAAE,CAAC;AAEjE,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAWD,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAA6B,CAAC;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAM/D,CAAC;AAEF;;;;;;;;;;;GAWG;AAGH,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,CAAC;AAEjG,+EAA+E;AAC/E,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAkED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAmBjE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GACzD,SAAS,MAAM,EAAE,CAOnB;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAEhG"}