@shrkcrft/inspector 0.1.0-alpha.1

package/dist/install-smoke.js

@@ -0,0 +1,31 @@
+/**
+ * `shrk install smoke` — verify the installed CLI is callable.
+ *
+ * Declares a deterministic plan of safe commands to run after install (no
+ * network, no shell tricks). The CLI command runs each plan step with the
+ * inherited environment and reports pass/fail per step.
+ *
+ * Plan steps:
+ *  - resolve the local `shrk` binary
+ *  - shrk version
+ *  - shrk help
+ *  - shrk commands primary
+ *  - shrk runtime doctor
+ *  - shrk release readiness (only if inside the SharkCraft repo)
+ */
+export const INSTALL_SMOKE_SCHEMA = 'sharkcraft.install-smoke/v1';
+const PLAN = [
+    { id: 'version', title: 'shrk version', command: ['shrk', 'version'] },
+    { id: 'help', title: 'shrk help', command: ['shrk', '--help'], optional: true },
+    { id: 'primary', title: 'shrk commands primary', command: ['shrk', 'commands', 'primary'] },
+    { id: 'runtime-doctor', title: 'shrk runtime doctor', command: ['shrk', 'runtime', 'doctor'], optional: true },
+    {
+        id: 'release-readiness',
+        title: 'shrk release readiness',
+        command: ['shrk', 'release', 'readiness'],
+        requiresRepo: true,
+    },
+];
+export function getInstallSmokePlan() {
+    return PLAN;
+}

package/dist/knowledge-authoring.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Knowledge authoring preview.
+ *
+ * Pure, deterministic builders that take a structured authoring request
+ * (add / update / remove) and return a draft + patch preview. Preview-only:
+ * this module never writes — the CLI adapter materialises the preview under
+ * `.sharkcraft/authoring/` (drafts) or `.sharkcraft/fixes/` (lint output).
+ *
+ * Hard rules:
+ *   - No mutation of `sharkcraft/knowledge.ts` or any pack `assets/knowledge.ts`.
+ *   - Generated content references real, deterministic IKnowledgeEntry fields.
+ *   - Add refuses to overwrite an existing id unless told to.
+ *   - Update preserves all unspecified fields verbatim.
+ *   - Remove always reports reverse references and refuses by default if any
+ *     remain.
+ */
+import type { IKnowledgeAnchor, IKnowledgeEntry, IKnowledgeReference } from '@shrkcrft/knowledge';
+export declare const KNOWLEDGE_AUTHORING_SCHEMA = "sharkcraft.knowledge-authoring/v1";
+export declare enum KnowledgeAuthoringOperation {
+    Add = "add",
+    Update = "update",
+    Remove = "remove"
+}
+export interface IKnowledgeAuthoringInput {
+    operation: KnowledgeAuthoringOperation;
+    /** Target entry id. Required for all operations. */
+    id: string;
+    /** Used by `add` (and as an override for `update`). */
+    title?: string;
+    /** IKnowledgeEntry.type. Defaults to 'documentation' for add. */
+    type?: string;
+    /** IKnowledgeEntry.priority. Defaults to 'medium' for add. */
+    priority?: 'critical' | 'high' | 'medium' | 'low';
+    /** Free-text body. */
+    content?: string;
+    /** Optional one-line summary. */
+    summary?: string;
+    /** Scope tags. */
+    scope?: readonly string[];
+    /** Tags. */
+    tags?: readonly string[];
+    /** appliesWhen lifecycle markers. */
+    appliesWhen?: readonly string[];
+    /** Related entry ids. */
+    related?: readonly string[];
+    /** References to add/replace. */
+    references?: readonly IKnowledgeReference[];
+    /** Anchors to add/replace. */
+    anchors?: readonly IKnowledgeAnchor[];
+    /** Action hints raw object (optional). */
+    actionHints?: Record<string, unknown>;
+    /** Patch operations for update only — incremental changes that
+     * preserve unspecified fields. */
+    updateOps?: IKnowledgeUpdateOps;
+    /** Provenance reason — recorded in the draft + provenance ledger. */
+    reason?: string;
+    /** Optional pack/local target hint (for the explainer). */
+    target?: IKnowledgeAuthoringTarget;
+    /** When true (Remove only) — produce the preview even if reverse
+     * references exist. Default false → returns a refused result. */
+    forcePreview?: boolean;
+    /** Treats add of an existing id as an update. Default false. */
+    allowOverwrite?: boolean;
+}
+export interface IKnowledgeUpdateOps {
+    addReferences?: readonly IKnowledgeReference[];
+    removeReferences?: readonly {
+        kind: string;
+        id?: string;
+        path?: string;
+        symbol?: string;
+    }[];
+    addAnchors?: readonly IKnowledgeAnchor[];
+    removeAnchorIds?: readonly string[];
+    addRelated?: readonly string[];
+    removeRelated?: readonly string[];
+    setSummary?: string;
+    setContent?: string;
+    setPriority?: 'critical' | 'high' | 'medium' | 'low';
+    /** Set `metadata.deprecated = true` (preserved as a metadata field). */
+    markDeprecated?: boolean;
+    /** Clear deprecated flag. */
+    unmarkDeprecated?: boolean;
+}
+export interface IKnowledgeAuthoringTarget {
+    /** 'local' = sharkcraft/knowledge.ts, 'pack' = a pack assets/knowledge.ts. */
+    kind: 'local' | 'pack';
+    /** Project-relative file the human would copy the draft into. */
+    filePath?: string;
+    /** Pack package name when kind === 'pack'. */
+    packName?: string;
+}
+export interface IKnowledgeAuthoringDraftFile {
+    path: string;
+    body: string;
+    language: 'typescript' | 'json' | 'markdown';
+}
+export interface IKnowledgeAuthoringResult {
+    schema: typeof KNOWLEDGE_AUTHORING_SCHEMA;
+    generatedAt: string;
+    operation: KnowledgeAuthoringOperation;
+    entryId: string;
+    /** False when the operation was refused (e.g. remove with reverse
+     * references and no --force-preview). */
+    ok: boolean;
+    /** When ok=false, this explains why. */
+    refusal?: string;
+    /** The TS draft an agent can paste into the target knowledge file. */
+    tsDraft: IKnowledgeAuthoringDraftFile;
+    /** Machine manifest summarising the planned change. */
+    jsonManifest: IKnowledgeAuthoringDraftFile;
+    /** Markdown explainer + next commands. */
+    explainer: IKnowledgeAuthoringDraftFile;
+    /** Optional JSON patch — semantic diff for update/remove. */
+    patch?: IKnowledgeAuthoringPatch;
+    /** Warnings (do not fail generation). */
+    warnings: readonly string[];
+    /** Next commands an agent should run after applying the draft. */
+    nextCommands: readonly string[];
+    /** For update/remove — the resolved current entry (before change). */
+    current?: IKnowledgeEntry;
+    /** For update — the projected entry shape after applying ops. */
+    next?: IKnowledgeEntry;
+    /** For remove — entries that still reference this id (advisory ladder). */
+    reverseReferences?: readonly IReverseReference[];
+    /** True if a deprecation was suggested instead of removal. */
+    suggestedDeprecationInstead?: boolean;
+}
+export interface IReverseReference {
+    fromEntryId: string;
+    field: 'related' | 'reference.id' | 'reference.symbol' | 'reference.path' | 'anchor.targetId';
+    note?: string;
+}
+export interface IKnowledgeAuthoringPatch {
+    schema: 'sharkcraft.knowledge-authoring-patch/v1';
+    operation: KnowledgeAuthoringOperation;
+    entryId: string;
+    changes: readonly IKnowledgeAuthoringPatchChange[];
+}
+export interface IKnowledgeAuthoringPatchChange {
+    op: 'add' | 'remove' | 'replace';
+    field: string;
+    before?: unknown;
+    after?: unknown;
+}
+export interface IKnowledgeAuthoringContext {
+    /** Currently loaded entries — used for reverse-ref + duplicate detection. */
+    entries: readonly IKnowledgeEntry[];
+}
+export declare function buildKnowledgeAuthoringPreview(input: IKnowledgeAuthoringInput, context: IKnowledgeAuthoringContext): IKnowledgeAuthoringResult;
+//# sourceMappingURL=knowledge-authoring.d.ts.map

package/dist/knowledge-authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-authoring.d.ts","sourceRoot":"","sources":["../src/knowledge-authoring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,oBAAY,2BAA2B;IACrC,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,2BAA2B,CAAC;IACvC,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClD,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,YAAY;IACZ,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,qCAAqC;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,yBAAyB;IACzB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iCAAiC;IACjC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,8BAA8B;IAC9B,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC;sCACkC;IAClC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,yBAAyB,CAAC;IACnC;qEACiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,gBAAgB,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5F,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACzC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrD,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,6BAA6B;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,2BAA2B,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB;6CACyC;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,4BAA4B,CAAC;IACtC,uDAAuD;IACvD,YAAY,EAAE,4BAA4B,CAAC;IAC3C,0CAA0C;IAC1C,SAAS,EAAE,4BAA4B,CAAC;IACxC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,yCAAyC;IACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,kEAAkE;IAClE,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,sEAAsE;IACtE,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,iEAAiE;IACjE,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,8DAA8D;IAC9D,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,GAAG,cAAc,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,yCAAyC,CAAC;IAClD,SAAS,EAAE,2BAA2B,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,8BAA8B,EAAE,CAAC;CACpD;AAED,MAAM,WAAW,8BAA8B;IAC7C,EAAE,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CACrC;AAuVD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CA4P3B"}