@skill-map/cli 0.54.0 → 0.56.0

package/dist/kernel/index.d.ts

@@ -1,87 +1,3 @@
-/**
- * Extension registry, six kinds, first-class, loaded through a single API.
- *
- * The `IExtension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
- * Kind-specific manifests (provider / extractor / analyzer / action / formatter /
- * hook) extend this base structurally; the registry stores the base view
- * and each kind's code carries its own fuller type where needed.
- *
- * **Spec § A.6, qualified ids.** Every extension is keyed in the registry
- * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash-command`,
- * `my-plugin/my-extractor`). `IExtension.id` carries the **short** id as authored;
- * `IExtension.pluginId` carries the namespace; the registry composes the
- * qualifier internally and exposes lookup APIs that operate on either form
- * (qualified for direct lookup, kind-scoped listing for enumeration).
- *
- * Boot invariant: `new Registry()` is empty. `registry.totalCount() === 0`
- * when the kernel boots with zero extensions. This is the data side of the
- * `kernel-empty-boot` conformance contract.
- */
-type ExtensionKind = 'provider' | 'extractor' | 'analyzer' | 'action' | 'formatter' | 'hook';
-declare const EXTENSION_KINDS: readonly ExtensionKind[];
-interface IExtension {
-    /** Short (unqualified) extension id, injected by the loader from the leaf folder name. */
-    id: string;
-    /** Owning plugin namespace, injected by the loader from the plugin folder name. */
-    pluginId: string;
-    kind: ExtensionKind;
-    version: string;
-    /** Required short description; surfaced in `sm <kind>s list` and the UI. */
-    description: string;
-    entry?: string;
-}
-/**
- * Compose the qualified registry key for an extension. Single source of
- * truth so callers don't reinvent the format and a future change (e.g. a
- * different separator) lands in one place.
- */
-declare function qualifiedExtensionId(pluginId: string, id: string): string;
-declare class DuplicateExtensionError extends Error {
-    constructor(kind: ExtensionKind, qualifiedId: string);
-}
-declare class Registry {
-    #private;
-    constructor();
-    register(ext: IExtension): void;
-    /**
-     * Lookup by qualified id (`<pluginId>/<id>`). Returns `undefined` when
-     * no extension of that kind is registered under the qualifier.
-     */
-    get(kind: ExtensionKind, qualifiedId: string): IExtension | undefined;
-    /**
-     * Convenience wrapper that composes the qualified id for the caller.
-     * Equivalent to `get(kind, qualifiedExtensionId(pluginId, id))`.
-     */
-    find(kind: ExtensionKind, pluginId: string, id: string): IExtension | undefined;
-    all(kind: ExtensionKind): IExtension[];
-    count(kind: ExtensionKind): number;
-    totalCount(): number;
-}
-
-/**
- * Step 9.6.6, runtime annotation-contribution catalog types.
- *
- * Lives in its own module (rather than `kernel/index.ts`) so consumers
- * deep inside the kernel, `IAnalyzerContext`, the BFF route factories,
- * future Action contexts, can depend on the catalog shape without
- * dragging the whole kernel barrel and risking a cycle.
- */
-/**
- * Single row of the runtime annotation-contribution catalog surfaced by
- * `kernel.getRegisteredAnnotationKeys()`. One row per (plugin × key)
- * tuple. Built-in catalog keys from `annotations.schema.json` are NOT
- * included, this catalog is plugin-only; the UI knows the built-in
- * catalog via the schema bundle.
- */
-interface IRegisteredAnnotationKey {
-    pluginId: string;
-    key: string;
-    location: 'namespaced' | 'root';
-    ownership: 'exclusive' | 'shared';
-    /** Inline JSON Schema as declared in the manifest (not the AJV compiled validator). */
-    schema: Record<string, unknown>;
-}
-
 /**
  * Closed enum of view slot names. Mirror of
  * `spec/schemas/view-slots.schema.json#/$defs/SlotName`.
@@ -91,7 +7,7 @@ type TSlotName = 'card.title.right' | 'card.subtitle.left' | 'card.footer.left'
  * Closed enum of input-type names for plugin settings. Mirror of
  * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
  */
-type TInputTypeName = 'string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list';
+type TInputTypeName = 'string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'number' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list';
 /**
  * Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by counter, tag, alert, and icon slots for color/contrast hints. The UI maps each severity to a theme-aware tint; plugins do not pick raw colors.
  */
@@ -199,7 +115,7 @@ interface ActionPrompt {
     /**
      * Input-type id from the closed catalog. The UI renders the matching control before dispatch (`single-string`, `enum-pick` and `string-list` today; other types degrade to a graceful 'unsupported' notice).
      */
-    inputType: ('string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list') & string;
+    inputType: ('string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'number' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list') & string;
     /**
      * Key under which the collected value is placed in the dispatch `input` body.
      */
@@ -474,6 +390,13 @@ interface ISetting_Integer extends ISettingCommon {
     max?: number;
     step?: number;
 }
+interface ISetting_Number extends ISettingCommon {
+    type: 'number';
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
 interface ISetting_EnumOption {
     value: string;
     label: string;
@@ -530,7 +453,7 @@ interface ISetting_KeyValueList extends ISettingCommon {
  *
  * Mirror of `input-types.schema.json#/$defs/ISettingDeclaration`.
  */
-type TSettingDeclaration = ISetting_StringList | ISetting_SingleString | ISetting_BooleanFlag | ISetting_Integer | ISetting_EnumPick | ISetting_EnumMultipick | ISetting_PathGlob | ISetting_Regex | ISetting_Secret | ISetting_KeyValueList;
+type TSettingDeclaration = ISetting_StringList | ISetting_SingleString | ISetting_BooleanFlag | ISetting_Integer | ISetting_Number | ISetting_EnumPick | ISetting_EnumMultipick | ISetting_PathGlob | ISetting_Regex | ISetting_Secret | ISetting_KeyValueList;
 /**
  * Runtime value type for a setting, derived from its declaration. The
  * kernel exposes settings to extractors as `Record<string, TSettingValue>`
@@ -554,13 +477,24 @@ type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueLis
  */
 
 /**
- * Lifecycle label an extension manifest MAY declare. Presentation-only
- * metadata: the non-default values render as a badge next to the
- * extension in `sm plugins list` / `sm plugins show` and the Settings
- * plugins panel, and the kernel never gates behaviour on it (a
- * `deprecated` extension still runs). Default: missing == `stable`,
- * and `stable` (declared or defaulted) renders no badge. Mirrors
+ * Lifecycle label an extension manifest MAY declare. Renders as a badge
+ * next to the extension in `sm plugins list <id>` / `sm plugins show` and
+ * the Settings plugins panel for the non-default values.
+ *
+ * Two values ALSO change behaviour: `experimental` (not ready yet) and
+ * `deprecated` (on its way out) flip the extension's installed default
+ * to DISABLED, so the extension does not load (does not run, does not
+ * register) unless the operator opts in (`sm plugins enable
+ * <plugin>/<ext>`, the Settings toggle, or a `settings.json` /
+ * `config_plugins` override). The opt-in is a plain enable override,
+ * once set it wins over the installed default exactly like any other
+ * extension (so a deprecated extension can still be kept running during
+ * a migration). The remaining values are presentation-only and default
+ * to ENABLED: `beta` runs by default with a badge, `stable` (declared
+ * or defaulted) runs with no badge. Missing == `stable` == enabled, no
+ * badge. Mirrors
  * `spec/schemas/extensions/base.schema.json#/properties/stability`.
+ *
  * Deliberately a superset of the node-level annotations enum (which has
  * no `beta`): this describes the maturity of the extension itself, not
  * of a scanned node.
@@ -620,8 +554,9 @@ interface IExtensionBase {
     description: string;
     /**
      * Optional lifecycle label (`experimental` / `beta` / `stable` /
-     * `deprecated`). Missing == `stable`, no badge rendered. See
-     * `TExtensionStability` for the full semantics.
+     * `deprecated`). Missing == `stable`, no badge rendered. `experimental`
+     * and `deprecated` additionally flip the installed default to disabled.
+     * See `TExtensionStability` for the full semantics.
      */
     stability?: TExtensionStability;
     /**
@@ -657,14 +592,107 @@ interface IExtensionBase {
      * `viewContributions` with the structure-as-truth refactor. Each
      * entry maps a local contribution id (kebab-case, unique within the
      * extension) to an `IViewContribution` that picks a view slot by
-     * name from the closed catalog. Only `extractor` and `analyzer` kinds
-     * may declare this field.
+     * name from the closed catalog. Declared by `extractor` and
+     * `analyzer` kinds (emitted during scan / graph evaluation) and by
+     * `action` kinds (emitted from the Action's scan-time `project()`
+     * self-projection, see `IActionProjectionContext`).
      */
     ui?: Record<string, IViewContribution>;
     /** Runtime-only, absolute path of the extension entry file. */
     entry?: string;
 }
 
+/**
+ * Extension registry, six kinds, first-class, loaded through a single API.
+ *
+ * The `IExtension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
+ * Kind-specific manifests (provider / extractor / analyzer / action / formatter /
+ * hook) extend this base structurally; the registry stores the base view
+ * and each kind's code carries its own fuller type where needed.
+ *
+ * **Spec § A.6, qualified ids.** Every extension is keyed in the registry
+ * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash-command`,
+ * `my-plugin/my-extractor`). `IExtension.id` carries the **short** id as authored;
+ * `IExtension.pluginId` carries the namespace; the registry composes the
+ * qualifier internally and exposes lookup APIs that operate on either form
+ * (qualified for direct lookup, kind-scoped listing for enumeration).
+ *
+ * Boot invariant: `new Registry()` is empty. `registry.totalCount() === 0`
+ * when the kernel boots with zero extensions. This is the data side of the
+ * `kernel-empty-boot` conformance contract.
+ */
+
+type ExtensionKind = 'provider' | 'extractor' | 'analyzer' | 'action' | 'formatter' | 'hook';
+declare const EXTENSION_KINDS: readonly ExtensionKind[];
+interface IExtension {
+    /** Short (unqualified) extension id, injected by the loader from the leaf folder name. */
+    id: string;
+    /** Owning plugin namespace, injected by the loader from the plugin folder name. */
+    pluginId: string;
+    kind: ExtensionKind;
+    version: string;
+    /** Required short description; surfaced in `sm <kind>s list` and the UI. */
+    description: string;
+    /**
+     * Optional lifecycle label (`IExtensionBase.stability`). Carried on the
+     * registry view so the enabled-resolver can read it: `experimental`
+     * flips an extension's installed default to disabled. Absent == stable.
+     */
+    stability?: TExtensionStability;
+    entry?: string;
+}
+/**
+ * Compose the qualified registry key for an extension. Single source of
+ * truth so callers don't reinvent the format and a future change (e.g. a
+ * different separator) lands in one place.
+ */
+declare function qualifiedExtensionId(pluginId: string, id: string): string;
+declare class DuplicateExtensionError extends Error {
+    constructor(kind: ExtensionKind, qualifiedId: string);
+}
+declare class Registry {
+    #private;
+    constructor();
+    register(ext: IExtension): void;
+    /**
+     * Lookup by qualified id (`<pluginId>/<id>`). Returns `undefined` when
+     * no extension of that kind is registered under the qualifier.
+     */
+    get(kind: ExtensionKind, qualifiedId: string): IExtension | undefined;
+    /**
+     * Convenience wrapper that composes the qualified id for the caller.
+     * Equivalent to `get(kind, qualifiedExtensionId(pluginId, id))`.
+     */
+    find(kind: ExtensionKind, pluginId: string, id: string): IExtension | undefined;
+    all(kind: ExtensionKind): IExtension[];
+    count(kind: ExtensionKind): number;
+    totalCount(): number;
+}
+
+/**
+ * Step 9.6.6, runtime annotation-contribution catalog types.
+ *
+ * Lives in its own module (rather than `kernel/index.ts`) so consumers
+ * deep inside the kernel, `IAnalyzerContext`, the BFF route factories,
+ * future Action contexts, can depend on the catalog shape without
+ * dragging the whole kernel barrel and risking a cycle.
+ */
+/**
+ * Single row of the runtime annotation-contribution catalog surfaced by
+ * `kernel.getRegisteredAnnotationKeys()`. One row per (plugin × key)
+ * tuple. Built-in catalog keys from `annotations.schema.json` are NOT
+ * included, this catalog is plugin-only; the UI knows the built-in
+ * catalog via the schema bundle.
+ */
+interface IRegisteredAnnotationKey {
+    pluginId: string;
+    key: string;
+    location: 'namespaced' | 'root';
+    ownership: 'exclusive' | 'shared';
+    /** Inline JSON Schema as declared in the manifest (not the AJV compiled validator). */
+    schema: Record<string, unknown>;
+}
+
 /**
  * Domain types, byte-aligned with `spec/schemas/{node,link,issue,scan-result}.schema.json`.
  *
@@ -897,6 +925,16 @@ interface Node {
     externalRefs?: IExternalRef[];
     frontmatter?: Record<string, unknown>;
     tokens?: TripleSplit;
+    /**
+     * File modification time (`mtime`) in Unix milliseconds, captured at
+     * scan time from the on-disk `lstat`. Absent for virtual / derived
+     * nodes (`virtual === true`, no backing file) and for nodes built by a
+     * Provider `walk()` that does not stat its sources. Persisted to
+     * `scan_nodes.modified_at_ms` and surfaced on `/api/nodes` /
+     * `/api/scan` so the UI can show and sort a "last modified" column.
+     * NOT content: never participates in `bodyHash` / `frontmatterHash`.
+     */
+    modifiedAtMs?: number;
     /**
      * Step 9.6.2, sidecar denormalisation surface. Populated by the
      * orchestrator at scan time; absent when the orchestrator did not
@@ -2190,6 +2228,15 @@ interface IRawNode {
     frontmatterRaw: string;
     /** Parsed frontmatter, or `{}` when absent / unparseable. */
     frontmatter: Record<string, unknown>;
+    /**
+     * File modification time (`mtime`) in Unix milliseconds, captured by
+     * the kernel walker from the same `lstat` that guards the read (zero
+     * extra syscalls). Threaded onto the persisted `Node` as
+     * `modifiedAtMs`. Optional: a Provider that ships its own `walk()` and
+     * does not stat its sources MAY omit it; virtual / derived nodes carry
+     * no file and never set it.
+     */
+    modifiedAtMs?: number;
     /**
      * Parser diagnostics (audit L1). Populated by the walker when the
      * parser surfaced `IParseIssue` entries (e.g. malformed YAML).
@@ -2893,6 +2940,12 @@ interface IAnalyzerOrphanSidecar {
 interface IAnalyzerContext {
     nodes: Node[];
     links: Link[];
+    /**
+     * Resolved values of the analyzer's declared `settings`, populated
+     * from project config + user overrides. Empty object when no settings
+     * are declared.
+     */
+    settings: Record<string, unknown>;
     /**
      * Step 9.6.2, orphaned sidecars discovered during the scan walk.
      * Empty when sidecar discovery did not run (legacy callers) or
@@ -2984,6 +3037,20 @@ interface IAnalyzerContext {
      * `runScan` sites that never wired the field through).
      */
     reservedNodePaths?: ReadonlySet<string>;
+    /**
+     * Links the post-walk lift judged genuinely broken: target matches no
+     * node `path` AND the stripped trigger matches no entry in the cross-
+     * kind name index (`spec/architecture.md` §Provider · resolution
+     * rules). Computed once per scan by the orchestrator from the same
+     * `deriveNodeIdentifiers`-backed index the confidence-lift transform
+     * uses, so a link that resolves only via a filename / dirname
+     * identifier is NOT in the set. Membership is by object identity (the
+     * orchestrator threads the SAME link objects). The single consumer is
+     * `core/reference-broken`, which projects one issue per member (after
+     * its `referenceablePaths` escape hatch). Absent for legacy callers
+     * that never wired the field through, the rule then emits nothing.
+     */
+    brokenLinks?: ReadonlySet<Link>;
     /**
      * Absolute path of the scan's project root (cwd of the invocation).
      * Threaded into the analyzer pass so an analyzer that needs to
@@ -3126,6 +3193,32 @@ interface IActionContext {
      */
     settings: Record<string, unknown>;
 }
+/**
+ * Read-only graph context handed to an Action's scan-time `project()`
+ * method. Mirrors the Analyzer emit path (`IAnalyzerContext`): the
+ * Action sees the full merged graph (`nodes` + `links`) and emits its
+ * own per-node view contributions via `emitContribution`, supplying the
+ * target node path explicitly because, like the Analyzer, it walks the
+ * whole graph rather than running per-node.
+ *
+ * The contribution is declared in the Action's manifest `ui` map and
+ * passed BY REFERENCE (same object-identity model as Extractor /
+ * Analyzer emit). The orchestrator validates the payload against the
+ * slot's schema at call time, dropping invalid emissions with an
+ * `extension.error` event.
+ *
+ * `project()` is strictly DETERMINISTIC and side-effect-free: no writes,
+ * no runner, no IO. It runs during the scan's contribution phase on
+ * EVERY scan, exactly like an Analyzer's emit path, so its cost is the
+ * same per-scan cost as today's projector analyzers. Even an Action
+ * whose `invoke` is `mode: 'probabilistic'` MUST keep `project()`
+ * deterministic, only `invoke` may be probabilistic.
+ */
+interface IActionProjectionContext {
+    readonly nodes: readonly Node[];
+    readonly links: readonly Link[];
+    emitContribution(nodePath: string, ref: IViewContribution, payload: unknown): void;
+}
 /**
  * Declarative filter applied by `--all` fan-out, UI button gating, and
  * `sm actions show`. Same shape used by Extractor and Analyzer so the
@@ -3182,6 +3275,23 @@ interface IAction extends IExtensionBase {
      * kernel materialises any returned `writes` after the call.
      */
     invoke?: <TInput, TReport>(input: TInput, ctx: IActionContext) => IActionResult<TReport>;
+    /**
+     * Optional scan-time self-projection. When present, the orchestrator
+     * calls it during the contribution phase (right after the analyzer
+     * pass) with read-only graph access, and the Action emits its OWN
+     * `inspector.action.button` (or any declared `ui` contribution) per
+     * node. This replaces the former "projector analyzer" pattern: the
+     * button now lives with the Action that dispatches it, not in a
+     * sibling Analyzer.
+     *
+     * MUST be deterministic and side-effect-free (no writes, no runner,
+     * no IO), exactly like an Analyzer's emit path. The button declares
+     * its own qualified id as `actionId` in the payload. Actions that ship
+     * for the future probabilistic runner / record path leave it absent;
+     * an Action MAY declare both `project` and `invoke` (advertiser +
+     * executor), or only one.
+     */
+    project?(ctx: IActionProjectionContext): void;
 }
 
 /**
@@ -3202,6 +3312,12 @@ interface IFormatterContext {
     nodes: Node[];
     links: Link[];
     issues: Issue[];
+    /**
+     * Resolved values of the formatter's declared `settings`, populated
+     * from project config + user overrides. Empty object when no settings
+     * are declared.
+     */
+    settings: Record<string, unknown>;
     /**
      * Full persisted scan, when the caller has it on hand. Optional so
      * formatters that only consume (nodes, links, issues) keep working
@@ -3305,6 +3421,12 @@ declare const HOOK_TRIGGERS: readonly THookTrigger[];
  * Deterministic hooks SHOULD ignore the field.
  */
 interface IHookContext {
+    /**
+     * Resolved values of the hook's declared `settings`, populated from
+     * project config + user overrides. Empty object when no settings are
+     * declared.
+     */
+    settings: Record<string, unknown>;
     /** The raw event the dispatcher matched. */
     event: {
         type: THookTrigger;
@@ -3648,6 +3770,16 @@ interface IScanExtensions {
      * advisory until the job subsystem ships once the job subsystem ships.
      */
     hooks?: IHook[];
+    /**
+     * Optional enabled actions. When supplied, the orchestrator runs the
+     * action-projection pass right after the analyzer pass: every action
+     * carrying a scan-time `project()` self-projection emits its own view
+     * contributions (e.g. `inspector.action.button`) onto the merged
+     * graph. Actions without `project` (only `invoke`) ride along inert.
+     * Absent → no projection pass runs (the gate is the composed enabled
+     * set, so a disabled / experimental action never reaches here).
+     */
+    actions?: IAction[];
 }
 interface RunScanOptions {
     /**