@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/surface/not-enabled-error.d.ts

@@ -1,11 +1,17 @@
+import { type ParsedArgs } from '../command-registry.js';
+import type { ISurfaceDenial } from './i-surface-denial.js';
+import { SurfaceRefusalReason } from './surface-refusal-reason.js';
 /**
- * Structured error returned when a user / agent invokes an
- * experimental command that is not enabled in the current repo's
- * `sharkcraft.config.ts surface.enabled[]`.
+ * Structured error returned when a user / agent invokes a command the
+ * surface gate refuses in the current repo: an experimental command not in
+ * `sharkcraft.config.ts surface.enabled[]`, a tool-maintenance command
+ * outside SharkCraft's own repository, or a command a `surface.disabled`
+ * selector denies.
  *
  * Exit code distinguishes "command exists but is gated" from
  * "command unknown" (which exits 2 via the did-you-mean path in
- * main.ts).
+ * main.ts) and from any check verdict (0/1/2) — a gated command is never a
+ * check failure.
  */
 export declare const SURFACE_NOT_ENABLED_EXIT_CODE = 78;
 export declare const SURFACE_NOT_ENABLED_SCHEMA = "sharkcraft.surface.not-enabled.v1";
@@ -13,12 +19,40 @@ export interface ISurfaceNotEnabledError {
     schema: typeof SURFACE_NOT_ENABLED_SCHEMA;
     command: string;
     tier: 'experimental';
+    /** Why the gate refused (round 11): `experimental` · `tool-maintenance` · `disabled`. */
+    reasonCode: SurfaceRefusalReason;
     reason: string;
     enableCommand: string;
     explainCommand: string;
 }
+/** A view the gate may refuse — the fields of `ISurfaceCommandView` the refusal reads. */
+interface IGatedView {
+    readonly command: string;
+    readonly source: string;
+    readonly detail?: string;
+    readonly deniedBy?: ISurfaceDenial;
+}
 export declare function makeSurfaceNotEnabledError(command: string, options?: {
     reason?: string;
 }): ISurfaceNotEnabledError;
+/**
+ * THE refusal for a non-callable surface view. The CLI surface gate renders
+ * it (exit 78) and the MCP gate sends its reason, so both name the same cause
+ * and the same remedy.
+ */
+export declare function surfaceRefusalFor(view: IGatedView): ISurfaceNotEnabledError;
 export declare function renderSurfaceNotEnabledText(err: ISurfaceNotEnabledError): string;
+/**
+ * THE writer of a CLI surface refusal — which stream gets which form. A caller
+ * that asked for the machine form (`--json`, or `--format json`) gets the
+ * structured refusal (`schema` + `reasonCode`) on STDOUT, the channel every
+ * `--json` body uses, and stderr stays empty; otherwise the text goes to
+ * STDERR and stdout stays empty. (The docs promised the JSON body; the gate
+ * printed the text alone, so an agent branching on `reasonCode` got nothing.)
+ */
+export declare function surfaceRefusalOutput(err: ISurfaceNotEnabledError, args: ParsedArgs): {
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export {};
 //# sourceMappingURL=not-enabled-error.d.ts.map

package/dist/surface/not-enabled-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"not-enabled-error.d.ts","sourceRoot":"","sources":["../../src/surface/not-enabled-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,uBAAuB,CAWzB;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,uBAAuB,GAC3B,MAAM,CAaR"}
+{"version":3,"file":"not-enabled-error.d.ts","sourceRoot":"","sources":["../../src/surface/not-enabled-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,yFAAyF;IACzF,UAAU,EAAE,oBAAoB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0FAA0F;AAC1F,UAAU,UAAU;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,uBAAuB,CAYzB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,uBAAuB,CAiC3E;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,uBAAuB,GAC3B,MAAM,CA0CR;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,uBAAuB,EAC5B,IAAI,EAAE,UAAU,GACf;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKtD"}

package/dist/surface/not-enabled-error.js

@@ -1,11 +1,18 @@
+import { flagBool, flagString } from "../command-registry.js";
+import { SurfaceLayer } from "./surface-layer.js";
+import { SurfaceRefusalReason } from "./surface-refusal-reason.js";
+import { TierSource } from "./tier.js";
 /**
- * Structured error returned when a user / agent invokes an
- * experimental command that is not enabled in the current repo's
- * `sharkcraft.config.ts surface.enabled[]`.
+ * Structured error returned when a user / agent invokes a command the
+ * surface gate refuses in the current repo: an experimental command not in
+ * `sharkcraft.config.ts surface.enabled[]`, a tool-maintenance command
+ * outside SharkCraft's own repository, or a command a `surface.disabled`
+ * selector denies.
  *
  * Exit code distinguishes "command exists but is gated" from
  * "command unknown" (which exits 2 via the did-you-mean path in
- * main.ts).
+ * main.ts) and from any check verdict (0/1/2) — a gated command is never a
+ * check failure.
  */
 export const SURFACE_NOT_ENABLED_EXIT_CODE = 78;
 export const SURFACE_NOT_ENABLED_SCHEMA = 'sharkcraft.surface.not-enabled.v1';
@@ -14,14 +21,79 @@ export function makeSurfaceNotEnabledError(command, options = {}) {
         schema: SURFACE_NOT_ENABLED_SCHEMA,
         command,
         tier: 'experimental',
+        reasonCode: SurfaceRefusalReason.Experimental,
         reason: options.reason ??
             `Command \`${command}\` is an experimental tier — not enabled in this repo.`,
-        enableCommand: `shrk surface enable ${command}`,
-        explainCommand: `shrk surface explain ${command}`,
+        enableCommand: `shrk surface enable ${shellWord(command)}`,
+        explainCommand: `shrk surface explain ${shellWord(command)}`,
     };
 }
+/**
+ * THE refusal for a non-callable surface view. The CLI surface gate renders
+ * it (exit 78) and the MCP gate sends its reason, so both name the same cause
+ * and the same remedy.
+ */
+export function surfaceRefusalFor(view) {
+    const explainCommand = `shrk surface explain ${shellWord(view.command)}`;
+    if (view.source === TierSource.ToolMaintenance) {
+        return {
+            schema: SURFACE_NOT_ENABLED_SCHEMA,
+            command: view.command,
+            tier: 'experimental',
+            reasonCode: SurfaceRefusalReason.ToolMaintenance,
+            reason: `\`${view.command}\` maintains SharkCraft itself and does not apply to this repository — this is not a check failure.`,
+            enableCommand: `shrk surface enable ${shellWord(view.command)} --write`,
+            explainCommand,
+        };
+    }
+    if (view.source === TierSource.Disabled && view.deniedBy) {
+        const { selector, origin } = view.deniedBy;
+        const byConfig = origin === SurfaceLayer.Config;
+        return {
+            schema: SURFACE_NOT_ENABLED_SCHEMA,
+            command: view.command,
+            tier: 'experimental',
+            reasonCode: SurfaceRefusalReason.Disabled,
+            reason: `\`${view.command}\` is disabled in this repository by ${byConfig ? `surface.disabled ('${selector}')` : `the active surface profile ('${selector}')`} — this is not a check failure.`,
+            // A config deny is undone where it was declared; a profile deny is
+            // overridden by an explicit config enable.
+            enableCommand: byConfig
+                ? `shrk surface allow ${shellWord(selector)} --write`
+                : `shrk surface enable ${shellWord(view.command)} --write`,
+            explainCommand,
+        };
+    }
+    return makeSurfaceNotEnabledError(view.command, view.detail ? { reason: view.detail } : {});
+}
 export function renderSurfaceNotEnabledText(err) {
     const lines = [];
+    switch (err.reasonCode) {
+        case SurfaceRefusalReason.ToolMaintenance:
+            lines.push(err.reason);
+            lines.push('');
+            lines.push("It checks SharkCraft's own sources (its docs set, examples, release artifacts or command catalog), " +
+                'so it is gated outside the SharkCraft repository.');
+            lines.push('');
+            lines.push('To run it anyway:');
+            lines.push(`  $ ${err.enableCommand}`);
+            lines.push('');
+            lines.push('Why it is gated:');
+            lines.push(`  $ ${err.explainCommand}`);
+            lines.push('');
+            return lines.join('\n');
+        case SurfaceRefusalReason.Disabled:
+            lines.push(err.reason);
+            lines.push('');
+            lines.push('To allow it again:');
+            lines.push(`  $ ${err.enableCommand}`);
+            lines.push('');
+            lines.push('Why it is gated:');
+            lines.push(`  $ ${err.explainCommand}`);
+            lines.push('');
+            return lines.join('\n');
+        case SurfaceRefusalReason.Experimental:
+            break;
+    }
     lines.push(`Command \`${err.command}\` exists but is not enabled in this repo.`);
     lines.push('');
     lines.push(`It is tier=${err.tier}. ${err.reason}`);
@@ -34,3 +106,21 @@ export function renderSurfaceNotEnabledText(err) {
     lines.push('');
     return lines.join('\n');
 }
+/**
+ * THE writer of a CLI surface refusal — which stream gets which form. A caller
+ * that asked for the machine form (`--json`, or `--format json`) gets the
+ * structured refusal (`schema` + `reasonCode`) on STDOUT, the channel every
+ * `--json` body uses, and stderr stays empty; otherwise the text goes to
+ * STDERR and stdout stays empty. (The docs promised the JSON body; the gate
+ * printed the text alone, so an agent branching on `reasonCode` got nothing.)
+ */
+export function surfaceRefusalOutput(err, args) {
+    const json = flagBool(args, 'json') || flagString(args, 'format') === 'json';
+    return json
+        ? { stdout: `${JSON.stringify(err, null, 2)}\n`, stderr: '' }
+        : { stdout: '', stderr: renderSurfaceNotEnabledText(err) };
+}
+/** A command path / selector as ONE shell word: quoted when it holds a space or a glob. */
+function shellWord(value) {
+    return /^[A-Za-z0-9._/:=@-]+$/.test(value) ? value : JSON.stringify(value);
+}

package/dist/surface/profiles.d.ts

@@ -23,6 +23,13 @@ export interface ISurfaceProfile {
      * classification, not paper over it.
      */
     enabled?: readonly string[];
+    /**
+     * Commands this profile DISABLES (round 11): not callable, absent from
+     * `--help`. Exact paths or `<group> *` selectors. An explicit
+     * `surface.enabled` entry in the project config overrides a profile's deny.
+     * Presets reach this through `surfaceProfile` — no preset schema change.
+     */
+    disabled?: readonly string[];
     /** Where the profile comes from (annotation for `surface explain`). */
     source: 'builtin' | 'pack' | 'local';
     /** When source='pack', the pack name. */

package/dist/surface/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/surface/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkLD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAOrD,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,eAAe,GAAG,SAAS,CAE7B"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/surface/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,uEAAuE;IACvE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkLD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAOrD,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,eAAe,GAAG,SAAS,CAE7B"}

package/dist/surface/resolve-command-string.d.ts

@@ -0,0 +1,10 @@
+import { type ICommandResolution, type ICommandResolveOptions } from '@shrkcrft/inspector';
+import type { ICommandIndex } from './i-command-index.js';
+import type { ICommandStringContext } from './i-command-string-context.js';
+/**
+ * Resolve one command string against the command index. Deterministic and
+ * pure. `options.assumeShrk` asks for the command-REFERENCE reading of a bare
+ * form (see the module comment).
+ */
+export declare function resolveCommandString(index: ICommandIndex, raw: string, ctx?: ICommandStringContext, options?: ICommandResolveOptions): ICommandResolution;
+//# sourceMappingURL=resolve-command-string.d.ts.map

package/dist/surface/resolve-command-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-command-string.d.ts","sourceRoot":"","sources":["../../src/surface/resolve-command-string.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAc7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAmnB3E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,qBAA0B,EAC/B,OAAO,GAAE,sBAA2B,GACnC,kBAAkB,CAYpB"}