@shrkcrft/inspector 0.1.0-alpha.2

package/dist/demo-workflow.js

@@ -0,0 +1,178 @@
+/**
+ * Demo-workflow generator. Renders ready-to-run CI workflow files that exercise
+ * SharkCraft's PR-review surface (impact + review packet + report site). The
+ * generator never executes anything and never makes external network calls.
+ * Workflows it emits never publish or post to PRs unless the human explicitly
+ * uncomments the optional steps.
+ */
+export const DEMO_WORKFLOW_SCHEMA = 'sharkcraft.demo-workflow/v1';
+function ghaPrReview(bun) {
+    const lines = [];
+    lines.push('# SharkCraft demo PR review workflow.');
+    lines.push('# Generated by `shrk demo workflow pr-review --provider github-actions`.');
+    lines.push('# - runs the read-only review surface on every PR.');
+    lines.push('# - no publishing, no posting comments by default.');
+    lines.push('# - uncomment the optional `gh pr comment` step to opt into PR comment posting.');
+    lines.push('name: SharkCraft PR review (demo)');
+    lines.push('on:');
+    lines.push('  pull_request:');
+    lines.push('    branches: [main]');
+    lines.push('jobs:');
+    lines.push('  sharkcraft-review:');
+    lines.push('    runs-on: ubuntu-latest');
+    lines.push('    timeout-minutes: 15');
+    lines.push('    permissions:');
+    lines.push('      contents: read');
+    lines.push('      # pull-requests: write   # only needed if you uncomment the gh pr comment step');
+    lines.push('    steps:');
+    lines.push('      - uses: actions/checkout@v4');
+    lines.push('        with:');
+    lines.push('          fetch-depth: 0');
+    lines.push('      - uses: oven-sh/setup-bun@v1');
+    lines.push(`        with: { bun-version: '${bun}' }`);
+    lines.push('      - run: bun install --frozen-lockfile');
+    lines.push('      - name: SharkCraft doctor');
+    lines.push('        run: bun run shrk doctor');
+    lines.push('      - name: Build review packet (v3)');
+    lines.push('        run: |');
+    lines.push('          mkdir -p .sharkcraft/reports');
+    lines.push('          bun run shrk review packet --v3 --since origin/main --json > .sharkcraft/reports/review.json');
+    lines.push('      - name: Compute impact since origin/main');
+    lines.push('        run: |');
+    lines.push('          bun run shrk impact --since origin/main --format json > .sharkcraft/reports/impact.json');
+    lines.push('          bun run shrk impact --since origin/main --format html --output .sharkcraft/reports/impact.html');
+    lines.push('      - name: Build static report site');
+    lines.push('        run: |');
+    lines.push('          bun run shrk report site \\');
+    lines.push('            --review .sharkcraft/reports/review.json \\');
+    lines.push('            --impact .sharkcraft/reports/impact.json \\');
+    lines.push('            --with-impact-graphs \\');
+    lines.push('            --output .sharkcraft/reports/site');
+    lines.push('      - name: Render PR comment (markdown)');
+    lines.push('        run: |');
+    lines.push('          bun run shrk review render-comment .sharkcraft/reports/review.json \\');
+    lines.push('            --output .sharkcraft/reports/review-comment.md');
+    lines.push('      # OPTIONAL: post the comment to the PR (requires permissions.pull-requests: write).');
+    lines.push('      # - name: Post review comment to PR');
+    lines.push('      #   env:');
+    lines.push('      #     GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}');
+    lines.push('      #   run: gh pr comment "${{ github.event.pull_request.number }}" --body-file .sharkcraft/reports/review-comment.md');
+    lines.push('      - name: Upload SharkCraft reports');
+    lines.push('        if: always()');
+    lines.push('        uses: actions/upload-artifact@v4');
+    lines.push('        with:');
+    lines.push('          name: sharkcraft-reports');
+    lines.push('          path: |');
+    lines.push('            .sharkcraft/reports/**');
+    lines.push('          if-no-files-found: ignore');
+    return lines.join('\n') + '\n';
+}
+function gitlabPrReview(bun) {
+    const lines = [];
+    lines.push('# SharkCraft demo PR review pipeline.');
+    lines.push('# Generated by `shrk demo workflow pr-review --provider gitlab`.');
+    lines.push('# - runs the read-only review surface on every MR.');
+    lines.push('# - no publishing, no posting comments by default.');
+    lines.push('');
+    lines.push('stages:');
+    lines.push('  - sharkcraft_review');
+    lines.push('');
+    lines.push('sharkcraft:pr-review:');
+    lines.push('  stage: sharkcraft_review');
+    lines.push(`  image: oven/bun:${bun}`);
+    lines.push('  rules:');
+    lines.push('    - if: $CI_PIPELINE_SOURCE == "merge_request_event"');
+    lines.push('  variables:');
+    lines.push('    GIT_DEPTH: "0"');
+    lines.push('  script:');
+    lines.push('    - bun install --frozen-lockfile');
+    lines.push('    - mkdir -p .sharkcraft/reports');
+    lines.push('    - bun run shrk doctor');
+    lines.push('    - bun run shrk review packet --v3 --since $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --json > .sharkcraft/reports/review.json');
+    lines.push('    - bun run shrk impact --since $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --format json > .sharkcraft/reports/impact.json');
+    lines.push('    - bun run shrk impact --since $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --format html --output .sharkcraft/reports/impact.html');
+    lines.push('    - bun run shrk report site --review .sharkcraft/reports/review.json --impact .sharkcraft/reports/impact.json --with-impact-graphs --output .sharkcraft/reports/site');
+    lines.push('    - bun run shrk review render-comment .sharkcraft/reports/review.json --output .sharkcraft/reports/review-comment.md');
+    lines.push('  artifacts:');
+    lines.push('    when: always');
+    lines.push('    paths:');
+    lines.push('      - .sharkcraft/reports/');
+    lines.push('    expire_in: 1 week');
+    lines.push('');
+    lines.push('# OPTIONAL: post the comment to the MR.');
+    lines.push('# Requires CI_JOB_TOKEN read access + python; commented out by default.');
+    lines.push('# sharkcraft:pr-comment:');
+    lines.push('#   stage: sharkcraft_review');
+    lines.push('#   needs: ["sharkcraft:pr-review"]');
+    lines.push('#   image: curlimages/curl');
+    lines.push('#   rules:');
+    lines.push('#     - if: $CI_PIPELINE_SOURCE == "merge_request_event"');
+    lines.push('#   script:');
+    lines.push('#     - "curl --request POST --header \\"PRIVATE-TOKEN: $REVIEW_TOKEN\\" --form body=@.sharkcraft/reports/review-comment.md $CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"');
+    return lines.join('\n') + '\n';
+}
+function bitbucketPrReview(bun) {
+    const lines = [];
+    lines.push('# SharkCraft demo PR review pipeline.');
+    lines.push('# Generated by `shrk demo workflow pr-review --provider bitbucket`.');
+    lines.push('# - runs the read-only review surface on every pull request.');
+    lines.push('# - no publishing, no posting comments by default.');
+    lines.push('');
+    lines.push(`image: oven/bun:${bun}`);
+    lines.push('');
+    lines.push('pipelines:');
+    lines.push('  pull-requests:');
+    lines.push('    "**":');
+    lines.push('      - step:');
+    lines.push('          name: SharkCraft PR review (demo)');
+    lines.push('          script:');
+    lines.push('            - bun install --frozen-lockfile');
+    lines.push('            - mkdir -p .sharkcraft/reports');
+    lines.push('            - bun run shrk doctor');
+    lines.push('            - bun run shrk review packet --v3 --since origin/$BITBUCKET_PR_DESTINATION_BRANCH --json > .sharkcraft/reports/review.json');
+    lines.push('            - bun run shrk impact --since origin/$BITBUCKET_PR_DESTINATION_BRANCH --format json > .sharkcraft/reports/impact.json');
+    lines.push('            - bun run shrk impact --since origin/$BITBUCKET_PR_DESTINATION_BRANCH --format html --output .sharkcraft/reports/impact.html');
+    lines.push('            - bun run shrk report site --review .sharkcraft/reports/review.json --impact .sharkcraft/reports/impact.json --with-impact-graphs --output .sharkcraft/reports/site');
+    lines.push('            - bun run shrk review render-comment .sharkcraft/reports/review.json --output .sharkcraft/reports/review-comment.md');
+    lines.push('          artifacts:');
+    lines.push('            - .sharkcraft/reports/**');
+    lines.push('');
+    lines.push('# OPTIONAL: post the comment to the PR using the Bitbucket REST API.');
+    lines.push('# Commented out by default; configure $BITBUCKET_TOKEN before enabling.');
+    return lines.join('\n') + '\n';
+}
+const NOTES = [
+    'Runs the read-only SharkCraft review surface — impact, review packet, report site.',
+    'Never publishes or posts to a PR by default. Optional comment-posting steps are commented out.',
+    'Uploads all generated artifacts so reviewers can download them from the CI run.',
+];
+export function defaultDemoWorkflowOutputPath(provider, kind = 'pr-review') {
+    if (provider === 'github-actions')
+        return `.github/workflows/sharkcraft-${kind}.yml`;
+    if (provider === 'gitlab')
+        return `.gitlab/${kind}-pipeline.yml`;
+    if (provider === 'bitbucket')
+        return `bitbucket-pipelines.${kind}.yml`;
+    return `sharkcraft-${kind}.yml`;
+}
+export function renderDemoWorkflow(provider, options = {}) {
+    const bun = options.bunVersion ?? '1.1.0';
+    const kind = options.kind ?? 'pr-review';
+    let body;
+    if (provider === 'github-actions')
+        body = ghaPrReview(bun);
+    else if (provider === 'gitlab')
+        body = gitlabPrReview(bun);
+    else if (provider === 'bitbucket')
+        body = bitbucketPrReview(bun);
+    else
+        throw new Error(`Unknown provider: ${provider}`);
+    return {
+        schema: DEMO_WORKFLOW_SCHEMA,
+        kind,
+        provider,
+        defaultOutputPath: defaultDemoWorkflowOutputPath(provider, kind),
+        body,
+        notes: NOTES,
+    };
+}

package/dist/dev-cycle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Dev cycle orchestrator.
+ *
+ * Plans (and renders) a deterministic sequence of read/check commands for a
+ * given dev-cycle profile. The actual *execution* lives in the CLI command;
+ * this module is pure data + planning.
+ *
+ * Profiles ship with the engine, and they all consist of read-only or
+ * preview-only commands. Auto-fix and auto-apply are never produced here.
+ */
+export declare const DEV_CYCLE_SCHEMA = "sharkcraft.dev-cycle/v1";
+export declare enum DevCycleProfileId {
+    SharkcraftSelf = "sharkcraft-self",
+    PackAuthor = "pack-author",
+    ProjectConsumer = "project-consumer",
+    Release = "release"
+}
+export interface IDevCycleStep {
+    readonly id: string;
+    readonly title: string;
+    readonly command: string;
+    readonly canFail: boolean;
+    readonly category: 'doctor' | 'check' | 'audit' | 'gate' | 'preview' | 'docs';
+}
+export interface IDevCycleProfile {
+    readonly id: DevCycleProfileId;
+    readonly title: string;
+    readonly description: string;
+    readonly steps: readonly IDevCycleStep[];
+}
+export declare const BUILTIN_DEV_CYCLE_PROFILES: readonly IDevCycleProfile[];
+export interface IDevCyclePlanReport {
+    readonly schema: typeof DEV_CYCLE_SCHEMA;
+    readonly profileId: DevCycleProfileId;
+    readonly profileTitle: string;
+    readonly steps: readonly IDevCycleStep[];
+    readonly notes: readonly string[];
+}
+export declare function planDevCycle(profileId: DevCycleProfileId): IDevCyclePlanReport | null;
+export declare function listDevCycleProfiles(): readonly IDevCycleProfile[];
+//# sourceMappingURL=dev-cycle.d.ts.map

package/dist/dev-cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-cycle.d.ts","sourceRoot":"","sources":["../src/dev-cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,oBAAY,iBAAiB;IAC3B,cAAc,oBAAoB;IAClC,UAAU,gBAAgB;IAC1B,eAAe,qBAAqB;IACpC,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;CAC/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AA0DD,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAKjE,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,gBAAgB,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,IAAI,CAcrF;AAED,wBAAgB,oBAAoB,IAAI,SAAS,gBAAgB,EAAE,CAElE"}

package/dist/dev-cycle.js

@@ -0,0 +1,94 @@
+/**
+ * Dev cycle orchestrator.
+ *
+ * Plans (and renders) a deterministic sequence of read/check commands for a
+ * given dev-cycle profile. The actual *execution* lives in the CLI command;
+ * this module is pure data + planning.
+ *
+ * Profiles ship with the engine, and they all consist of read-only or
+ * preview-only commands. Auto-fix and auto-apply are never produced here.
+ */
+export const DEV_CYCLE_SCHEMA = 'sharkcraft.dev-cycle/v1';
+export var DevCycleProfileId;
+(function (DevCycleProfileId) {
+    DevCycleProfileId["SharkcraftSelf"] = "sharkcraft-self";
+    DevCycleProfileId["PackAuthor"] = "pack-author";
+    DevCycleProfileId["ProjectConsumer"] = "project-consumer";
+    DevCycleProfileId["Release"] = "release";
+})(DevCycleProfileId || (DevCycleProfileId = {}));
+const SHARKCRAFT_SELF = {
+    id: DevCycleProfileId.SharkcraftSelf,
+    title: 'SharkCraft self — coherence + safety',
+    description: 'End-to-end cycle for working on the SharkCraft engine itself. All read-only / preview-only.',
+    steps: [
+        { id: 'doctor', title: 'Workspace doctor', command: 'shrk doctor', canFail: false, category: 'doctor' },
+        { id: 'self-config-doctor', title: 'Self-config doctor', command: 'shrk self-config doctor', canFail: true, category: 'doctor' },
+        { id: 'knowledge-stale-check', title: 'Knowledge stale-check (CI)', command: 'shrk knowledge stale-check --ci', canFail: true, category: 'gate' },
+        { id: 'templates-drift', title: 'Templates drift (warning+)', command: 'shrk templates drift --min-severity warning', canFail: true, category: 'gate' },
+        { id: 'test-agent', title: 'Agent contract tests', command: 'shrk test agent', canFail: false, category: 'gate' },
+        { id: 'commands-doctor', title: 'Commands doctor', command: 'shrk commands doctor', canFail: true, category: 'doctor' },
+        { id: 'safety-audit', title: 'Safety audit (deep)', command: 'shrk safety audit --deep', canFail: false, category: 'audit' },
+    ],
+};
+const PACK_AUTHOR = {
+    id: DevCycleProfileId.PackAuthor,
+    title: 'Pack author — quality + contributions',
+    description: 'Cycle for authoring or maintaining a SharkCraft pack.',
+    steps: [
+        { id: 'packs-doctor', title: 'Packs doctor', command: 'shrk packs doctor', canFail: true, category: 'doctor' },
+        { id: 'packs-contributions', title: 'Packs contributions inventory', command: 'shrk packs contributions', canFail: true, category: 'audit' },
+        { id: 'packs-conflicts', title: 'Packs conflicts', command: 'shrk packs conflicts', canFail: true, category: 'audit' },
+        { id: 'helper-doctor', title: 'Helper doctor (engine helpers)', command: 'shrk helper doctor', canFail: true, category: 'doctor' },
+        { id: 'feedback-rules-doctor', title: 'Feedback rules doctor', command: 'shrk feedback rules doctor', canFail: true, category: 'doctor' },
+        { id: 'self-config-doctor', title: 'Self-config doctor', command: 'shrk self-config doctor', canFail: true, category: 'doctor' },
+    ],
+};
+const PROJECT_CONSUMER = {
+    id: DevCycleProfileId.ProjectConsumer,
+    title: 'Project consumer — daily dev safety',
+    description: 'Daily safety loop for a project that consumes SharkCraft packs.',
+    steps: [
+        { id: 'doctor', title: 'Workspace doctor', command: 'shrk doctor', canFail: false, category: 'doctor' },
+        { id: 'boundaries-changed-only', title: 'Boundaries (changed-only)', command: 'shrk check boundaries --changed-only', canFail: true, category: 'gate' },
+        { id: 'conventions-check', title: 'Conventions check (changed)', command: 'shrk conventions check', canFail: true, category: 'gate' },
+        { id: 'knowledge-stale-check', title: 'Knowledge stale-check', command: 'shrk knowledge stale-check', canFail: true, category: 'gate' },
+        { id: 'templates-drift', title: 'Templates drift', command: 'shrk templates drift', canFail: true, category: 'gate' },
+    ],
+};
+const RELEASE = {
+    id: DevCycleProfileId.Release,
+    title: 'Release — preflight + readiness',
+    description: 'Cycle for shipping a release. Read-only inspection; humans run the actual publish.',
+    steps: [
+        { id: 'release-readiness', title: 'Release readiness (strict)', command: 'shrk release readiness --strict', canFail: false, category: 'gate' },
+        { id: 'release-smoke', title: 'Release smoke (default scenarios)', command: 'shrk release smoke', canFail: true, category: 'gate' },
+        { id: 'safety-audit', title: 'Safety audit', command: 'shrk safety audit', canFail: false, category: 'audit' },
+        { id: 'product-check', title: 'Product check', command: 'shrk product check', canFail: true, category: 'gate' },
+        { id: 'commands-doctor', title: 'Commands doctor', command: 'shrk commands doctor', canFail: true, category: 'doctor' },
+    ],
+};
+export const BUILTIN_DEV_CYCLE_PROFILES = [
+    SHARKCRAFT_SELF,
+    PACK_AUTHOR,
+    PROJECT_CONSUMER,
+    RELEASE,
+];
+export function planDevCycle(profileId) {
+    const p = BUILTIN_DEV_CYCLE_PROFILES.find((x) => x.id === profileId);
+    if (!p)
+        return null;
+    return {
+        schema: DEV_CYCLE_SCHEMA,
+        profileId: p.id,
+        profileTitle: p.title,
+        steps: p.steps,
+        notes: [
+            'All steps are read-only / preview-only. The cycle never auto-applies.',
+            'When a step exits non-zero, the loop stops unless --continue-on-error is set.',
+            'Run with --until-green to repeat until every non-`canFail` step passes.',
+        ],
+    };
+}
+export function listDevCycleProfiles() {
+    return BUILTIN_DEV_CYCLE_PROFILES;
+}

package/dist/dev-session-html.d.ts

@@ -0,0 +1,13 @@
+import { type IDevSessionLoad } from './dev-session.js';
+export interface IRenderDevSessionHtmlOptions {
+    /** Computed next-action hint. */
+    nextActionLine?: string;
+    /** Whether to include file:// links to local session files. Default true. */
+    includeFileLinks?: boolean;
+}
+/**
+ * Render a fully self-contained HTML report for a dev session. No external
+ * assets, no JS, no network — works as a local file via `file://`.
+ */
+export declare function renderDevSessionHtml(load: IDevSessionLoad, options?: IRenderDevSessionHtmlOptions): string;
+//# sourceMappingURL=dev-session-html.d.ts.map

package/dist/dev-session-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-session-html.d.ts","sourceRoot":"","sources":["../src/dev-session-html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEzE,MAAM,WAAW,4BAA4B;IAC3C,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,4BAAiC,GACzC,MAAM,CAmCR"}

package/dist/dev-session-html.js

@@ -0,0 +1,223 @@
+import { DevSessionPhase } from "./dev-session.js";
+/**
+ * Render a fully self-contained HTML report for a dev session. No external
+ * assets, no JS, no network — works as a local file via `file://`.
+ */
+export function renderDevSessionHtml(load, options = {}) {
+    const state = load.state;
+    const task = load.task || state?.task || '(unknown task)';
+    const includeLinks = options.includeFileLinks !== false;
+    const sections = [];
+    sections.push(`<h1>Dev session: ${esc(load.id)}</h1>`);
+    sections.push(`<p class="task"><strong>Task:</strong> ${esc(task)}</p>`);
+    if (state) {
+        sections.push(`<dl class="meta">
+      <dt>Phase</dt><dd><span class="phase phase-${esc(state.phase)}">${esc(state.phase)}</span></dd>
+      <dt>Created</dt><dd>${esc(state.createdAt)}</dd>
+      <dt>Updated</dt><dd>${esc(state.updatedAt)}</dd>
+      <dt>Project root</dt><dd><code>${esc(state.projectRoot)}</code></dd>
+    </dl>`);
+    }
+    else {
+        sections.push('<p class="warn">Legacy session (no session.json) — details are limited to on-disk artifacts.</p>');
+    }
+    sections.push(renderTimeline(load));
+    sections.push(renderPlans(load, includeLinks));
+    sections.push(renderAppliedPlans(load));
+    sections.push(renderValidations(load));
+    sections.push(renderReports(load, includeLinks));
+    sections.push(renderCommands(load));
+    sections.push(renderRisks(load));
+    if (options.nextActionLine) {
+        sections.push(`<h2>Next action</h2><pre class="next">${esc(options.nextActionLine)}</pre>`);
+    }
+    else if (state?.nextAction) {
+        sections.push(`<h2>Next action</h2><pre class="next">${esc(state.nextAction)}</pre>`);
+    }
+    return wrapHtml(`SharkCraft session ${load.id}`, sections.join('\n'));
+}
+function renderTimeline(load) {
+    const state = load.state;
+    if (!state) {
+        return `<h2>Timeline</h2><p>No session.json — timeline reconstructed from filesystem only.</p>`;
+    }
+    const rows = [];
+    rows.push(`<tr><td>${esc(state.createdAt)}</td><td>session started</td></tr>`);
+    for (const p of state.plans) {
+        const verb = p.status === 'intent' ? 'intent created' : 'plan saved';
+        rows.push(`<tr><td>${esc(p.createdAt)}</td><td>${esc(verb)}: <code>${esc(p.file)}</code> (template <code>${esc(p.templateId)}</code>)</td></tr>`);
+    }
+    for (const a of state.appliedPlans) {
+        rows.push(`<tr><td>${esc(a.appliedAt)}</td><td>applied plan <code>${esc(a.file)}</code></td></tr>`);
+    }
+    for (const v of state.validations) {
+        rows.push(`<tr><td>${esc(v.finishedAt)}</td><td>validation ${v.passed ? '<span class="ok">passed</span>' : '<span class="fail">FAILED</span>'} (${v.commandsRun.length} cmd, ${v.boundaryViolations} boundary)</td></tr>`);
+    }
+    if (state.phase === DevSessionPhase.Completed) {
+        rows.push(`<tr><td>${esc(state.updatedAt)}</td><td>session completed</td></tr>`);
+    }
+    return `<h2>Timeline</h2><table class="timeline"><tbody>${rows.join('\n')}</tbody></table>`;
+}
+function renderPlans(load, includeLinks) {
+    const state = load.state;
+    if (!state || state.plans.length === 0) {
+        return '<h2>Plans</h2><p><em>No plans saved.</em></p>';
+    }
+    const rows = state.plans.map((p) => {
+        const link = includeLinks ? `<a href="file://${esc(load.dir)}/plans/${esc(p.file)}">plans/${esc(p.file)}</a>` : `<code>plans/${esc(p.file)}</code>`;
+        const missing = p.missingVariables.length > 0
+            ? `<br><small>missing: ${p.missingVariables.map(esc).join(', ')}</small>`
+            : '';
+        const review = p.reviewReportFile
+            ? `<br><small>review: <code>reports/${esc(p.reviewReportFile)}</code></small>`
+            : '';
+        return `<tr>
+      <td><strong>${esc(p.name)}</strong></td>
+      <td>${esc(p.templateId)}</td>
+      <td>${link}${missing}${review}</td>
+      <td><span class="status status-${esc(p.status)}">${esc(p.status)}</span>${p.signed ? ' <span class="signed">signed</span>' : ''}</td>
+    </tr>`;
+    });
+    return `<h2>Plans</h2><table class="plans">
+    <thead><tr><th>Name</th><th>Template</th><th>File</th><th>Status</th></tr></thead>
+    <tbody>${rows.join('\n')}</tbody>
+  </table>`;
+}
+function renderAppliedPlans(load) {
+    const state = load.state;
+    if (!state || state.appliedPlans.length === 0) {
+        return '<h2>Applied plans</h2><p><em>None recorded (apply is the explicit human step).</em></p>';
+    }
+    const rows = state.appliedPlans.map((a) => {
+        const sig = a.signatureStatus ? `<small>signature: ${esc(a.signatureStatus)}</small>` : '';
+        const div = a.divergenceAccepted ? '<small class="warn"> · diverged</small>' : '';
+        const files = a.changedFiles && a.changedFiles.length > 0
+            ? `<details><summary>${a.changedFiles.length} file(s)</summary><ul>${a.changedFiles.map((f) => `<li><code>${esc(f)}</code></li>`).join('')}</ul></details>`
+            : '';
+        return `<tr><td><code>plans/${esc(a.file)}</code></td><td>${esc(a.appliedAt)}</td><td>${sig}${div}${files}</td></tr>`;
+    });
+    return `<h2>Applied plans</h2><table class="applied">
+    <thead><tr><th>File</th><th>Applied at</th><th>Details</th></tr></thead>
+    <tbody>${rows.join('\n')}</tbody>
+  </table>`;
+}
+function renderValidations(load) {
+    const state = load.state;
+    if (!state || state.validations.length === 0) {
+        return '<h2>Validations</h2><p><em>Not run.</em></p>';
+    }
+    const blocks = state.validations.map((v) => {
+        const cmds = v.commandsRun
+            .map((c) => `<li>${c.passed ? '<span class="ok">✓</span>' : '<span class="fail">✗</span>'} <code>${esc(c.command)}</code>${c.note ? ' — ' + esc(c.note) : ''}</li>`)
+            .join('');
+        return `<div class="validation ${v.passed ? 'pass' : 'fail'}">
+      <h3>${esc(v.finishedAt)} — ${v.passed ? '<span class="ok">PASSED</span>' : '<span class="fail">FAILED</span>'}</h3>
+      <p>Report: <code>reports/${esc(v.reportFile)}</code> · boundary=${v.boundaryViolations} · warnings=${v.warnings}</p>
+      <ul>${cmds}</ul>
+    </div>`;
+    });
+    return `<h2>Validations</h2>${blocks.join('\n')}`;
+}
+function renderReports(load, includeLinks) {
+    if (load.reportsOnDisk.length === 0) {
+        return '<h2>Reports</h2><p><em>No reports captured.</em></p>';
+    }
+    const items = load.reportsOnDisk
+        .map((r) => {
+        const link = includeLinks
+            ? `<a href="file://${esc(load.dir)}/reports/${esc(r)}">${esc(r)}</a>`
+            : `<code>${esc(r)}</code>`;
+        return `<li>${link}</li>`;
+    })
+        .join('');
+    return `<h2>Reports</h2><ul class="reports">${items}</ul>`;
+}
+function renderCommands(load) {
+    const id = load.id;
+    const cmds = [
+        ['plan', `shrk dev plan ${id} --template <id> --name <name> [--var k=v ...]`],
+        ['apply', `shrk apply .sharkcraft/sessions/${id}/plans/<plan>.json --verify-signature`],
+        ['apply (session-aware)', `shrk apply .sharkcraft/sessions/${id}/plans/<plan>.json --session ${id} --verify-signature`],
+        ['validate', `shrk dev validate ${id}`],
+        ['report', `shrk dev report ${id}`],
+    ];
+    return `<h2>Commands</h2><dl class="cmds">${cmds.map(([k, v]) => `<dt>${esc(k)}</dt><dd><pre>${esc(v)}</pre></dd>`).join('')}</dl>`;
+}
+function renderRisks(load) {
+    const state = load.state;
+    const risks = [];
+    if (state) {
+        const last = state.validations[state.validations.length - 1];
+        if (last && !last.passed)
+            risks.push('Last validation failed — review report before shipping.');
+        if (state.plans.some((p) => p.missingVariables.length > 0)) {
+            risks.push('One or more plans have unresolved variables (intent only).');
+        }
+        if (state.plans.length > 0 && state.appliedPlans.length === 0 && state.phase !== DevSessionPhase.Completed) {
+            risks.push('Plans saved but not applied — apply is the explicit human step.');
+        }
+        for (const w of state.warnings)
+            risks.push(w);
+    }
+    if (risks.length === 0) {
+        return '<h2>Remaining risks</h2><p><em>No risks flagged by deterministic checks.</em></p>';
+    }
+    return `<h2>Remaining risks</h2><ul class="risks">${risks.map((r) => `<li>${esc(r)}</li>`).join('')}</ul>`;
+}
+function wrapHtml(title, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${esc(title)}</title>
+<style>
+:root { color-scheme: light dark; --bg:#fff; --fg:#1c1c1f; --muted:#666; --accent:#2b6cb0; --ok:#1c7a3e; --warn:#a16207; --fail:#c0392b; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#1a1a1d; --fg:#e4e4e7; --muted:#a1a1aa; --accent:#60a5fa; --ok:#22c55e; --warn:#f59e0b; --fail:#ef4444; }
+}
+body { background: var(--bg); color: var(--fg); font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; margin: 0; padding: 2rem; max-width: 1024px; margin-left: auto; margin-right: auto; }
+h1, h2, h3 { line-height: 1.2; }
+h1 { font-size: 1.8rem; }
+h2 { margin-top: 2rem; border-bottom: 1px solid var(--muted); padding-bottom: .3rem; }
+code, pre { background: rgba(127,127,127,.12); padding: .1em .35em; border-radius: 3px; font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: .92em; }
+pre { padding: .65rem .8rem; overflow-x: auto; }
+dl.meta { display: grid; grid-template-columns: max-content 1fr; gap: .2rem 1rem; }
+dl.meta dt { color: var(--muted); }
+table { border-collapse: collapse; width: 100%; margin-top: .5rem; }
+th, td { text-align: left; padding: .35rem .6rem; border-bottom: 1px solid rgba(127,127,127,.18); vertical-align: top; }
+th { font-weight: 600; color: var(--muted); font-size: .85em; text-transform: uppercase; letter-spacing: .03em; }
+.ok { color: var(--ok); }
+.warn { color: var(--warn); }
+.fail { color: var(--fail); }
+.phase, .status { display: inline-block; padding: .1em .55em; border-radius: 3px; font-size: .85em; background: rgba(127,127,127,.18); }
+.phase-completed, .status-applied { background: rgba(34,197,94,.2); color: var(--ok); }
+.phase-validated { background: rgba(34,197,94,.2); color: var(--ok); }
+.phase-validation_failed { background: rgba(239,68,68,.2); color: var(--fail); }
+.phase-applied { background: rgba(45,127,255,.2); color: var(--accent); }
+.signed { background: rgba(34,197,94,.2); color: var(--ok); padding: .05em .35em; border-radius: 3px; font-size: .8em; }
+.validation { margin: .75rem 0; padding: .75rem 1rem; border-left: 3px solid var(--muted); }
+.validation.pass { border-color: var(--ok); }
+.validation.fail { border-color: var(--fail); }
+.next { background: rgba(45,127,255,.1); border-left: 3px solid var(--accent); }
+ul.risks li { color: var(--warn); }
+a { color: var(--accent); }
+.footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid rgba(127,127,127,.2); color: var(--muted); font-size: .85em; }
+</style>
+</head>
+<body>
+${body}
+<p class="footer">Generated by <code>shrk dev report --html</code> — fully local, no telemetry, no network.</p>
+</body>
+</html>
+`;
+}
+function esc(value) {
+    if (value === undefined || value === null)
+        return '';
+    return String(value)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

package/dist/dev-session-report.d.ts

@@ -0,0 +1,11 @@
+import { type IDevSessionLoad } from './dev-session.js';
+export interface IRenderDevSessionReportOptions {
+    /** Computed-next-action hint to append. Optional. */
+    nextActionLine?: string;
+}
+/**
+ * Render a human-readable audit-trail report for a dev session. Pure: takes
+ * the loaded session view + optional next-action hint, returns Markdown.
+ */
+export declare function renderDevSessionFinalReport(load: IDevSessionLoad, options?: IRenderDevSessionReportOptions): string;
+//# sourceMappingURL=dev-session-report.d.ts.map

package/dist/dev-session-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-session-report.d.ts","sourceRoot":"","sources":["../src/dev-session-report.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,8BAA8B;IAC7C,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,8BAAmC,GAC3C,MAAM,CA+LR"}