@thehumanpatternlab/hpl 1.0.2 → 1.0.3

package/dist/src/commands/capabilities.js

@@ -4,9 +4,9 @@
 import { Command } from "commander";
 import { writeHuman, writeJson } from "../io.js";
 import { EXIT } from "../contract/exitCodes.js";
-import { getAlphaIntent } from "../contract/intents";
-import { ok } from "../contract/envelope";
-import { getCapabilitiesAlpha } from "../contract/capabilities";
+import { getAlphaIntent } from "../contract/intents.js";
+import { ok } from "../contract/envelope.js";
+import { getCapabilitiesAlpha } from "../contract/capabilities.js";
 export function capabilitiesCommand() {
     return new Command("capabilities")
         .description("Show CLI capabilities for agents (contract: show_capabilities)")

package/dist/src/commands/version.js

@@ -5,8 +5,8 @@ import { Command } from "commander";
 import { writeHuman, writeJson } from "../io.js";
 import { EXIT } from "../contract/exitCodes.js";
 import { createRequire } from "node:module";
-import { getAlphaIntent } from "../contract/intents";
-import { ok } from "../contract/envelope";
+import { getAlphaIntent } from "../contract/intents.js";
+import { ok } from "../contract/envelope.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
 export function versionCommand() {

package/dist/src/contract/capabilities.js

@@ -4,8 +4,8 @@
    Purpose: Capability disclosure for AI agents (no assumptions).
    Contract: show_capabilities MUST emit tier, intents, schema versions.
    =========================================================== */
-import { CLI_SCHEMA_VERSION } from "./schema";
-import { listAlphaIntents } from "./intents";
+import { CLI_SCHEMA_VERSION } from "./schema.js";
+import { listAlphaIntents } from "./intents.js";
 export function getCapabilitiesAlpha() {
     return {
         intentTier: "alpha",

package/dist/src/contract/envelope.js

@@ -4,7 +4,7 @@
    Purpose: Single source of truth for contract-compliant JSON output.
    Guarantee: When --json, stdout emits JSON only (no logs).
    =========================================================== */
-import { CLI_SCHEMA_VERSION } from "./schema";
+import { CLI_SCHEMA_VERSION } from "./schema.js";
 export function ok(command, intent, data) {
     return { schemaVersion: CLI_SCHEMA_VERSION, command, status: "ok", intent, data };
 }

package/dist/src/http/client.js

@@ -5,7 +5,7 @@
    Notes:
      - Supports both raw API payloads and envelope form { ok: true, data: ... }.
    =========================================================== */
-import { getConfig } from "../config";
+import { getConfig } from "../config.js";
 export class HttpError extends Error {
     status;
     body;

package/dist/src/render/text.js

@@ -1,4 +1,4 @@
-import { formatTags, safeLine } from "./table";
+import { formatTags, safeLine } from "./table.js";
 export function stripHtml(input) {
     const s = (input || "");
     // Convert common structure to deterministic newlines first

package/package.json

@@ -1,72 +1,72 @@
-{
-  "name": "@thehumanpatternlab/hpl",
-  "version": "1.0.2",
-  "description": "AI-forward, automation-safe SDK and CLI for the Human Pattern Lab",
-  "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AdaInTheLab/the-human-pattern-lab-cli.git"
-  },
-  "homepage": "https://github.com/AdaInTheLab/the-human-pattern-lab-cli#readme",
-  "bugs": {
-    "url": "https://github.com/AdaInTheLab/the-human-pattern-lab-cli/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "bin": {
-    "hpl": "./dist/bin/hpl.js"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "dev": "tsx ./bin/hpl.ts",
-    "build": "tsc -p tsconfig.json",
-    "start": "node ./dist/bin/hpl.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "json:check": "tsx ./bin/hpl.ts --json version | node -e \"JSON.parse(require('fs').readFileSync(0,'utf8'))\"",
-    "lint": "node -e \"console.log('lint: add eslint when ready')\""
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "execa": "^9.6.1",
-    "gray-matter": "^4.0.3",
-    "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.19.3",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "vitest": "^4.0.16"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "human-pattern-lab",
-    "hpl",
-    "ai",
-    "ai-forward",
-    "automation",
-    "automation-safe",
-    "cli",
-    "sdk",
-    "developer-tools",
-    "observability",
-    "notes",
-    "knowledge-systems"
-  ]
-}
+{
+  "name": "@thehumanpatternlab/hpl",
+  "version": "1.0.3",
+  "description": "AI-forward, automation-safe SDK and CLI for the Human Pattern Lab",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdaInTheLab/the-human-pattern-lab-cli.git"
+  },
+  "homepage": "https://github.com/AdaInTheLab/the-human-pattern-lab-cli#readme",
+  "bugs": {
+    "url": "https://github.com/AdaInTheLab/the-human-pattern-lab-cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "hpl": "./dist/bin/hpl.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "tsx ./bin/hpl.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node ./dist/bin/hpl.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "json:check": "tsx ./bin/hpl.ts --json version | node -e \"JSON.parse(require('fs').readFileSync(0,'utf8'))\"",
+    "lint": "node -e \"console.log('lint: add eslint when ready')\""
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "execa": "^9.6.1",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "human-pattern-lab",
+    "hpl",
+    "ai",
+    "ai-forward",
+    "automation",
+    "automation-safe",
+    "cli",
+    "sdk",
+    "developer-tools",
+    "observability",
+    "notes",
+    "knowledge-systems"
+  ]
+}

package/dist/__tests__/config.test.js

@@ -1,22 +0,0 @@
-import { describe, expect, it, beforeEach } from 'vitest';
-import { SKULK_BASE_URL, SKULK_TOKEN } from '../lib/config.js';
-describe('env config', () => {
-    beforeEach(() => {
-        delete process.env.SKULK_BASE_URL;
-        delete process.env.SKULK_TOKEN;
-        delete process.env.HPL_API_BASE_URL;
-        delete process.env.HPL_TOKEN;
-    });
-    it('uses SKULK_TOKEN when set', () => {
-        process.env.SKULK_TOKEN = 'abc123';
-        expect(SKULK_TOKEN()).toBe('abc123');
-    });
-    it('uses SKULK_BASE_URL when set', () => {
-        process.env.SKULK_BASE_URL = 'https://example.com/api';
-        expect(SKULK_BASE_URL()).toBe('https://example.com/api');
-    });
-    it('override beats SKULK_BASE_URL', () => {
-        process.env.SKULK_BASE_URL = 'https://example.com/api';
-        expect(SKULK_BASE_URL('https://override.com/api')).toBe('https://override.com/api');
-    });
-});

package/dist/__tests__/outputContract.test.js

@@ -1,58 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { buildSyncReport } from '../cli/outputContract.js';
-describe('buildSyncReport (JSON contract)', () => {
-    it('counts synced in live mode (dryRun=false)', () => {
-        const report = buildSyncReport({
-            dryRun: false,
-            locale: 'en',
-            baseUrl: 'https://example.com/api',
-            results: [
-                { file: 'a.md', slug: 'a', status: 'ok', action: 'updated' },
-                { file: 'b.md', slug: 'b', status: 'ok', action: 'created' },
-            ],
-        });
-        expect(report.ok).toBe(true);
-        expect(report.summary).toEqual({
-            synced: 2,
-            dryRun: 0,
-            failed: 0,
-            total: 2,
-        });
-        expect(report.results.every((r) => r.written === true)).toBe(true);
-    });
-    it('counts dryRun in dry-run mode (dryRun=true)', () => {
-        const report = buildSyncReport({
-            dryRun: true,
-            results: [
-                { file: 'a.md', slug: 'a', status: 'dry-run' },
-                { file: 'b.md', slug: 'b', status: 'dry-run' },
-            ],
-        });
-        expect(report.ok).toBe(true);
-        expect(report.dryRun).toBe(true);
-        expect(report.summary).toEqual({
-            synced: 0,
-            dryRun: 2,
-            failed: 0,
-            total: 2,
-        });
-        expect(report.results.every((r) => r.written === false)).toBe(true);
-    });
-    it('normalizes legacy fail -> failed and keeps totals balanced', () => {
-        const report = buildSyncReport({
-            dryRun: false,
-            results: [
-                { file: 'a.md', slug: 'a', status: 'ok' },
-                { file: 'b.md', status: 'fail', error: 'boom' },
-            ],
-        });
-        expect(report.ok).toBe(false);
-        expect(report.summary).toEqual({
-            synced: 1,
-            dryRun: 0,
-            failed: 1,
-            total: 2,
-        });
-        expect(report.results[1].status).toBe('failed');
-    });
-});

package/dist/cli/output.js

@@ -1,21 +0,0 @@
-// Output is a contract. If it breaks, it should break loudly.
-function getRootCommand(cmd) {
-    let cur = cmd;
-    while (cur.parent)
-        cur = cur.parent;
-    return cur;
-}
-export function getOutputMode(cmd) {
-    const root = getRootCommand(cmd);
-    const opts = root.opts?.() ?? {};
-    return opts.json ? "json" : "human";
-}
-export function printJson(data) {
-    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
-}
-export function printError(message) {
-    process.stderr.write(message + "\n");
-}
-export function printJsonError(message, extra) {
-    process.stderr.write(JSON.stringify({ ok: false, error: { message, extra } }, null, 2) + "\n");
-}

package/dist/cli/outputContract.js

@@ -1,32 +0,0 @@
-// src/cli/outputContract.ts
-import { buildSyncSummary } from "../sync/summary.js";
-function normalizeResult(r, dryRunFlag) {
-    const status = r.status === "fail" ? "failed" : "ok"; // "dry-run" is not a failure
-    // If any result claims "dry-run", treat it as dry-run even if flag is off (safety)
-    const effectiveDryRun = dryRunFlag || r.status === "dry-run";
-    return {
-        file: r.file,
-        slug: r.slug,
-        status,
-        action: r.action,
-        error: r.error,
-        // written only when not dry-run and ok
-        written: !effectiveDryRun && status === "ok",
-    };
-}
-export function buildSyncReport(args) {
-    const { results, dryRun, locale, baseUrl } = args;
-    const normalized = results.map((r) => normalizeResult(r, dryRun));
-    // IMPORTANT: pass the effective dryRun mode you used for written calc
-    // If you want to be ultra strict, you could compute effectiveDryRun = dryRun || any(r.status==="dry-run")
-    const effectiveDryRun = dryRun || results.some((r) => r.status === "dry-run");
-    const summary = buildSyncSummary(normalized, effectiveDryRun);
-    return {
-        ok: summary.failed === 0,
-        summary,
-        results: normalized,
-        dryRun: effectiveDryRun,
-        locale,
-        baseUrl,
-    };
-}

package/dist/commands/notesSync.js

@@ -1,191 +0,0 @@
-/* ===========================================================
-   🦊 THE HUMAN PATTERN LAB — SKULK CLI
-   -----------------------------------------------------------
-   Author: Ada (Founder, The Human Pattern Lab)
-   Assistant: Lyric (AI Lab Companion)
-   File: notesSync.ts
-   Module: Notes Command Suite
-   Lab Unit: SCMS — Systems & Code Management Suite
-   Status: Active
-   -----------------------------------------------------------
-   Purpose:
-     Implements `skulk notes sync` — syncing local markdown Lab Notes
-     to the Lab API with predictable behavior in both human and
-     automation contexts.
-   -----------------------------------------------------------
-   Key Behaviors:
-     - Human mode: readable progress + summaries
-     - JSON mode (--json): stdout emits ONLY valid JSON (contract)
-     - Errors: stderr only
-     - Exit codes: deterministic (non-zero only on failure)
-   -----------------------------------------------------------
-   Notes:
-     JSON output is a contract. If it breaks, it should break loudly.
-   =========================================================== */
-/**
- * @file notesSync.ts
- * @author Ada
- * @assistant Lyric
- * @lab-unit SCMS — Systems & Code Management Suite
- * @since 2025-12-28
- * @description Syncs markdown Lab Notes to the API via `skulk notes sync`.
- *              Supports human + JSON output modes; JSON mode is stdout-pure.
- */
-import { Command } from 'commander';
-import { SKULK_BASE_URL, SKULK_TOKEN } from '../lib/config.js';
-import { httpJson } from '../lib/http.js';
-import { listMarkdownFiles, readNote } from '../lib/notes.js';
-import { getOutputMode, printJson } from '../cli/output.js';
-import { buildSyncReport } from '../cli/outputContract.js';
-import fs from 'node:fs';
-async function upsertNote(baseUrl, token, note, locale) {
-    const payload = {
-        slug: note.slug,
-        title: note.attributes.title,
-        markdown: note.markdown,
-        locale,
-    };
-    if (!payload.slug || !payload.title || !payload.markdown) {
-        throw new Error(`Invalid note payload: slug/title/markdown missing for ${payload.slug ?? 'unknown'}`);
-    }
-    return httpJson({ baseUrl, token }, 'POST', '/lab-notes/upsert', payload);
-}
-export function notesSyncCommand() {
-    const notes = new Command('notes').description('Lab Notes commands');
-    notes
-        .command('sync')
-        .description('Sync local markdown notes to the API')
-        .option('--dir <path>', 'Directory containing markdown notes', './src/labnotes/en')
-        //.option("--dir <path>", "Directory containing markdown notes", "./labnotes/en")
-        .option('--locale <code>', 'Locale code', 'en')
-        .option('--base-url <url>', 'Override API base URL (ex: https://thehumanpatternlab.com/api)')
-        .option('--dry-run', 'Print what would be sent, but do not call the API', false)
-        .option('--only <slug>', 'Sync only a single note by slug')
-        .option('--limit <n>', 'Sync only the first N notes', (v) => parseInt(v, 10))
-        .action(async (opts, cmd) => {
-        const mode = getOutputMode(cmd); // "json" | "human"
-        const jsonError = (message, extra) => {
-            if (mode === 'json') {
-                process.stderr.write(JSON.stringify({ ok: false, error: { message, extra } }, null, 2) +
-                    '\n');
-            }
-            else {
-                console.error(message);
-                if (extra)
-                    console.error(extra);
-            }
-            process.exitCode = 1;
-        };
-        if (!fs.existsSync(opts.dir)) {
-            jsonError(`Notes directory not found: ${opts.dir}`, {
-                hint: `Try: skulk notes sync --dir "..\\\\the-human-pattern-lab\\\\src\\\\labnotes\\\\en"`,
-            });
-            return;
-        }
-        const baseUrl = SKULK_BASE_URL(opts.baseUrl);
-        const token = SKULK_TOKEN();
-        const files = listMarkdownFiles(opts.dir);
-        let selectedFiles = files;
-        if (opts.only) {
-            selectedFiles = files.filter((f) => f.toLowerCase().includes(opts.only.toLowerCase()));
-        }
-        if (opts.limit && Number.isFinite(opts.limit)) {
-            selectedFiles = selectedFiles.slice(0, opts.limit);
-        }
-        if (selectedFiles.length === 0) {
-            if (mode === 'json') {
-                printJson({
-                    ok: true,
-                    action: 'noop',
-                    message: 'No matching notes found.',
-                    matched: 0,
-                });
-            }
-            else {
-                console.log('No matching notes found.');
-            }
-            process.exitCode = 0;
-            return;
-        }
-        // Human-mode header chatter
-        if (mode === 'human') {
-            console.log(`Skulk syncing ${selectedFiles.length} note(s) from ${opts.dir}`);
-            console.log(`API: ${baseUrl}`);
-            console.log(`Locale: ${opts.locale}`);
-            console.log(opts.dryRun ? 'Mode: DRY RUN (no writes)' : 'Mode: LIVE (writing)');
-        }
-        let ok = 0;
-        let fail = 0;
-        const results = [];
-        for (const file of selectedFiles) {
-            try {
-                const note = readNote(file, opts.locale);
-                if (opts.dryRun) {
-                    ok++;
-                    results.push({
-                        file,
-                        slug: note.slug,
-                        status: 'dry-run',
-                    });
-                    if (mode === 'human') {
-                        console.log(`\n---\n${note.slug}\n${file}\nfrontmatter keys: ${Object.keys(note.attributes).join(', ')}`);
-                    }
-                    continue;
-                }
-                const res = await upsertNote(baseUrl, token, note, opts.locale);
-                ok++;
-                results.push({
-                    file,
-                    slug: note.slug,
-                    status: 'ok',
-                    action: res.action,
-                });
-                if (mode === 'human') {
-                    console.log(`✅ ${note.slug} (${res.action ?? 'ok'})`);
-                }
-            }
-            catch (e) {
-                fail++;
-                const msg = String(e);
-                results.push({
-                    file,
-                    status: 'fail',
-                    error: msg,
-                });
-                if (mode === 'human') {
-                    console.error(`❌ ${file}`);
-                    console.error(msg);
-                }
-            }
-        }
-        if (mode === 'json') {
-            const report = buildSyncReport({
-                results,
-                dryRun: Boolean(opts.dryRun),
-                locale: opts.locale,
-                baseUrl,
-            });
-            printJson(report);
-            if (!report.ok)
-                process.exitCode = 1;
-        }
-        else {
-            const report = buildSyncReport({
-                results,
-                dryRun: Boolean(opts.dryRun),
-                locale: opts.locale,
-                baseUrl,
-            });
-            const { synced, dryRun, failed } = report.summary;
-            if (report.dryRun) {
-                console.log(`\nDone. ${dryRun} note(s) would be synced (dry-run). Failures: ${failed}`);
-            }
-            else {
-                console.log(`\nDone. ${synced} note(s) synced successfully. Failures: ${failed}`);
-            }
-            if (!report.ok)
-                process.exitCode = 1;
-        }
-    });
-    return notes;
-}

package/dist/commands/publish.js

@@ -1,36 +0,0 @@
-import { Command } from 'commander';
-import { loadMarkdown } from '../utils/loadMarkdown.js';
-import { LabClient } from '../sdk/LabClient.js';
-import path from 'path';
-const publish = new Command('publish')
-    .description('Publish a Lab Note from a Markdown file')
-    .argument('<file>', 'Markdown file to publish')
-    .option('-u, --url <url>', 'API base URL', 'https://thehumanpatternlab.com/api')
-    .option('-t, --token <token>', 'Auth token (if required)')
-    .action(async (file, options) => {
-    try {
-        const filePath = path.resolve(process.cwd(), file);
-        const { content, metadata } = loadMarkdown(filePath);
-        if (!metadata.title || !metadata.slug) {
-            console.error('Error: frontmatter must include at least: title, slug');
-            process.exit(1);
-        }
-        const client = new LabClient(options.url, options.token);
-        const payload = {
-            title: metadata.title,
-            slug: metadata.slug,
-            content,
-            tags: metadata.tags || [],
-            artifacts: metadata.artifacts || []
-        };
-        const result = await client.createOrUpdateNote(payload);
-        console.log(`✔ Published: ${metadata.title}`);
-        console.log(`→ slug: ${metadata.slug}`);
-        console.log(result.message);
-    }
-    catch (err) {
-        console.error('Publish failed:', err.message);
-        process.exit(1);
-    }
-});
-export default publish;

package/dist/index.js

@@ -1,36 +0,0 @@
-#!/usr/bin/env node
-/* ===========================================================
-   🦊 THE HUMAN PATTERN LAB — SKULK CLI
-   -----------------------------------------------------------
-   File: notesSync.ts
-   Role: Command Implementation
-   Author: Ada (The Human Pattern Lab)
-   Assistant: Lyric
-   Status: Active
-   Description:
-     Implements the `skulk notes sync` command.
-     Handles human-readable and machine-readable output modes
-     with enforced JSON purity for automation safety.
-   -----------------------------------------------------------
-   Design Notes:
-     - Output format is a contract
-     - JSON mode emits stdout-only structured data
-     - Errors are written to stderr
-     - Exit codes are deterministic
-   =========================================================== */
-import { Command } from "commander";
-import { notesSyncCommand } from "./commands/notesSync.js";
-const program = new Command();
-program
-    .name("skulk")
-    .description("Skulk CLI for The Human Pattern Lab")
-    .version("0.1.0")
-    .option("--json", "Output machine-readable JSON")
-    .configureHelp({ helpWidth: 100 });
-const argv = process.argv.slice(2);
-if (argv.length === 0) {
-    program.outputHelp();
-    process.exit(0);
-}
-program.addCommand(notesSyncCommand());
-program.parse(process.argv);

package/dist/lab.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import publishCommand from './commands/publish.js';
-const program = new Command();
-program
-    .name('lab')
-    .description('CLI tools for The Human Pattern Lab')
-    .version('0.1.0');
-program.addCommand(publishCommand);
-program.parse();

package/dist/lib/config.js

@@ -1,52 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { z } from 'zod';
-/**
- * Skulk CLI configuration schema
- * Stored in ~/.humanpatternlab/skulk.json
- */
-const ConfigSchema = z.object({
-    apiBaseUrl: z.string().url().default('https://thehumanpatternlab.com/api'),
-    token: z.string().optional(),
-});
-function getConfigPath() {
-    return path.join(os.homedir(), '.humanpatternlab', 'skulk.json');
-}
-export function loadConfig() {
-    const p = getConfigPath();
-    if (!fs.existsSync(p)) {
-        return ConfigSchema.parse({});
-    }
-    const raw = fs.readFileSync(p, 'utf-8');
-    return ConfigSchema.parse(JSON.parse(raw));
-}
-export function saveConfig(partial) {
-    const p = getConfigPath();
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    const current = loadConfig();
-    const next = ConfigSchema.parse({ ...current, ...partial });
-    fs.writeFileSync(p, JSON.stringify(next, null, 2), 'utf-8');
-}
-export function SKULK_BASE_URL(override) {
-    if (override?.trim())
-        return override.trim();
-    // NEW official env var
-    const env = process.env.SKULK_BASE_URL?.trim();
-    if (env)
-        return env;
-    // optional legacy support (remove later if you want)
-    const legacy = process.env.HPL_API_BASE_URL?.trim();
-    if (legacy)
-        return legacy;
-    return loadConfig().apiBaseUrl;
-}
-export function SKULK_TOKEN() {
-    const env = process.env.SKULK_TOKEN?.trim();
-    if (env)
-        return env;
-    const legacy = process.env.HPL_TOKEN?.trim();
-    if (legacy)
-        return legacy;
-    return loadConfig().token;
-}

package/dist/lib/http.js

@@ -1,18 +0,0 @@
-export async function httpJson(opts, method, path, body) {
-    const url = `${opts.baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
-    const headers = {
-        "Content-Type": "application/json"
-    };
-    if (opts.token)
-        headers["Authorization"] = `Bearer ${opts.token}`;
-    const res = await fetch(url, {
-        method,
-        headers,
-        body: body ? JSON.stringify(body) : undefined
-    });
-    const text = await res.text();
-    if (!res.ok) {
-        throw new Error(`HTTP ${res.status} ${res.statusText} @ ${url}\n${text}`);
-    }
-    return text ? JSON.parse(text) : {};
-}

package/dist/lib/notes.js

@@ -1,62 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import matter from "gray-matter";
-import { z } from "zod";
-const FrontmatterSchema = z.object({
-    id: z.string().optional(),
-    type: z.string().optional(),
-    title: z.string(),
-    subtitle: z.string().optional(),
-    published: z.string().optional(),
-    tags: z.array(z.string()).optional(),
-    summary: z.string().optional(),
-    readingTime: z.number().optional(),
-    status: z.enum(["published", "draft", "archived"]).optional(),
-    dept: z.string().optional(),
-    department_id: z.string().optional(),
-    shadow_density: z.number().optional(),
-    safer_landing: z.boolean().optional(),
-    slug: z.string().optional()
-});
-function slugFromFilename(filePath) {
-    const base = path.basename(filePath);
-    return base.replace(/\.mdx?$/i, "");
-}
-export function readNote(filePath, locale) {
-    const raw = fs.readFileSync(filePath, "utf-8");
-    const parsed = matter(raw);
-    const fm = FrontmatterSchema.parse(parsed.data ?? {});
-    const slug = (fm.slug && String(fm.slug).trim()) || slugFromFilename(filePath);
-    const body = parsed.content.trim();
-    const markdown = body.length > 0 ? body : raw.trim();
-    // Keep full attributes, but ensure key stuff exists
-    const title = (fm.title && String(fm.title).trim()) || "";
-    if (!title) {
-        throw new Error(`Missing required frontmatter: title (${filePath})`);
-    }
-    if (!markdown) {
-        throw new Error(`Missing required markdown content (${filePath})`);
-    }
-    return {
-        slug,
-        locale,
-        attributes: { ...fm, slug },
-        markdown
-    };
-}
-export function listMarkdownFiles(dir) {
-    const out = [];
-    const stack = [dir];
-    while (stack.length) {
-        const d = stack.pop();
-        const entries = fs.readdirSync(d, { withFileTypes: true });
-        for (const e of entries) {
-            const p = path.join(d, e.name);
-            if (e.isDirectory())
-                stack.push(p);
-            else if (e.isFile() && /\.mdx?$/i.test(e.name))
-                out.push(p);
-        }
-    }
-    return out.sort();
-}

package/dist/lib/output.js

@@ -1,21 +0,0 @@
-// Output is a contract. If it breaks, it should break loudly.
-function getRootCommand(cmd) {
-    let cur = cmd;
-    while (cur.parent)
-        cur = cur.parent;
-    return cur;
-}
-export function getOutputMode(cmd) {
-    const root = getRootCommand(cmd);
-    const opts = root.opts?.() ?? {};
-    return opts.json ? "json" : "human";
-}
-export function printJson(data) {
-    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
-}
-export function printError(message) {
-    process.stderr.write(message + "\n");
-}
-export function printJsonError(message, extra) {
-    process.stderr.write(JSON.stringify({ ok: false, error: { message, extra } }, null, 2) + "\n");
-}

package/dist/sdk/LabClient.js

@@ -1,94 +0,0 @@
-// src/sdk/LabClient.ts
-export class LabClient {
-    baseUrl;
-    token;
-    constructor(baseUrl, token) {
-        this.baseUrl = baseUrl.replace(/\/$/, '');
-        this.token = token;
-    }
-    setToken(token) {
-        this.token = token;
-    }
-    headers() {
-        const h = {
-            'Content-Type': 'application/json'
-        };
-        if (this.token) {
-            h['Authorization'] = `Bearer ${this.token}`;
-        }
-        return h;
-    }
-    //
-    // ────────────────────────────────────────────────
-    //   PUBLIC ROUTES
-    // ────────────────────────────────────────────────
-    //
-    async getAllNotes() {
-        const res = await fetch(`${this.baseUrl}/`, {
-            method: 'GET',
-            headers: this.headers()
-        });
-        if (!res.ok)
-            throw new Error('Failed to fetch notes');
-        return res.json();
-    }
-    async getNoteBySlug(slug) {
-        const res = await fetch(`${this.baseUrl}/notes/${slug}`, {
-            method: 'GET',
-            headers: this.headers()
-        });
-        if (!res.ok)
-            throw new Error('Note not found');
-        return res.json();
-    }
-    //
-    // ────────────────────────────────────────────────
-    //   ADMIN ROUTES
-    // ────────────────────────────────────────────────
-    //
-    async getAdminNotes() {
-        const res = await fetch(`${this.baseUrl}/api/admin/notes`, {
-            method: 'GET',
-            credentials: 'include',
-            headers: this.headers()
-        });
-        if (!res.ok)
-            throw new Error('Failed to fetch admin notes');
-        return res.json();
-    }
-    async createOrUpdateNote(input) {
-        const res = await fetch(`${this.baseUrl}/api/admin/notes`, {
-            method: 'POST',
-            credentials: 'include',
-            headers: this.headers(),
-            body: JSON.stringify(input)
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({}));
-            throw new Error(err.error || 'Failed to save note');
-        }
-        return res.json();
-    }
-    async deleteNote(id) {
-        const res = await fetch(`${this.baseUrl}/api/admin/notes/${id}`, {
-            method: 'DELETE',
-            credentials: 'include',
-            headers: this.headers()
-        });
-        if (!res.ok)
-            throw new Error('Failed to delete note');
-        return res.json();
-    }
-    //
-    // ────────────────────────────────────────────────
-    //   HEALTH
-    // ────────────────────────────────────────────────
-    //
-    async health() {
-        const res = await fetch(`${this.baseUrl}/api/health`, {
-            method: 'GET',
-            headers: this.headers()
-        });
-        return res.json();
-    }
-}

package/dist/src/__tests__/config.test.js

@@ -1,22 +0,0 @@
-import { describe, expect, it, beforeEach } from 'vitest';
-import { SKULK_BASE_URL, SKULK_TOKEN } from '../lib/config.js';
-describe('env config', () => {
-    beforeEach(() => {
-        delete process.env.SKULK_BASE_URL;
-        delete process.env.SKULK_TOKEN;
-        delete process.env.HPL_API_BASE_URL;
-        delete process.env.HPL_TOKEN;
-    });
-    it('uses SKULK_TOKEN when set', () => {
-        process.env.SKULK_TOKEN = 'abc123';
-        expect(SKULK_TOKEN()).toBe('abc123');
-    });
-    it('uses SKULK_BASE_URL when set', () => {
-        process.env.SKULK_BASE_URL = 'https://example.com/api';
-        expect(SKULK_BASE_URL()).toBe('https://example.com/api');
-    });
-    it('override beats SKULK_BASE_URL', () => {
-        process.env.SKULK_BASE_URL = 'https://example.com/api';
-        expect(SKULK_BASE_URL('https://override.com/api')).toBe('https://override.com/api');
-    });
-});

package/dist/src/__tests__/outputContract.test.js

@@ -1,58 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { buildSyncReport } from '../cli/outputContract.js';
-describe('buildSyncReport (JSON contract)', () => {
-    it('counts synced in live mode (dryRun=false)', () => {
-        const report = buildSyncReport({
-            dryRun: false,
-            locale: 'en',
-            baseUrl: 'https://example.com/api',
-            results: [
-                { file: 'a.md', slug: 'a', status: 'ok', action: 'updated' },
-                { file: 'b.md', slug: 'b', status: 'ok', action: 'created' },
-            ],
-        });
-        expect(report.ok).toBe(true);
-        expect(report.summary).toEqual({
-            synced: 2,
-            dryRun: 0,
-            failed: 0,
-            total: 2,
-        });
-        expect(report.results.every((r) => r.written === true)).toBe(true);
-    });
-    it('counts dryRun in dry-run mode (dryRun=true)', () => {
-        const report = buildSyncReport({
-            dryRun: true,
-            results: [
-                { file: 'a.md', slug: 'a', status: 'dry-run' },
-                { file: 'b.md', slug: 'b', status: 'dry-run' },
-            ],
-        });
-        expect(report.ok).toBe(true);
-        expect(report.dryRun).toBe(true);
-        expect(report.summary).toEqual({
-            synced: 0,
-            dryRun: 2,
-            failed: 0,
-            total: 2,
-        });
-        expect(report.results.every((r) => r.written === false)).toBe(true);
-    });
-    it('normalizes legacy fail -> failed and keeps totals balanced', () => {
-        const report = buildSyncReport({
-            dryRun: false,
-            results: [
-                { file: 'a.md', slug: 'a', status: 'ok' },
-                { file: 'b.md', status: 'fail', error: 'boom' },
-            ],
-        });
-        expect(report.ok).toBe(false);
-        expect(report.summary).toEqual({
-            synced: 1,
-            dryRun: 0,
-            failed: 1,
-            total: 2,
-        });
-        expect(report.results[1].status).toBe('failed');
-    });
-});

package/dist/src/commands/notesSync.js

@@ -1,191 +0,0 @@
-/* ===========================================================
-   🦊 THE HUMAN PATTERN LAB — SKULK CLI
-   -----------------------------------------------------------
-   Author: Ada (Founder, The Human Pattern Lab)
-   Assistant: Lyric (AI Lab Companion)
-   File: notesSync.ts
-   Module: Notes Command Suite
-   Lab Unit: SCMS — Systems & Code Management Suite
-   Status: Active
-   -----------------------------------------------------------
-   Purpose:
-     Implements `skulk notes sync` — syncing local markdown Lab Notes
-     to the Lab API with predictable behavior in both human and
-     automation contexts.
-   -----------------------------------------------------------
-   Key Behaviors:
-     - Human mode: readable progress + summaries
-     - JSON mode (--json): stdout emits ONLY valid JSON (contract)
-     - Errors: stderr only
-     - Exit codes: deterministic (non-zero only on failure)
-   -----------------------------------------------------------
-   Notes:
-     JSON output is a contract. If it breaks, it should break loudly.
-   =========================================================== */
-/**
- * @file notesSync.ts
- * @author Ada
- * @assistant Lyric
- * @lab-unit SCMS — Systems & Code Management Suite
- * @since 2025-12-28
- * @description Syncs markdown Lab Notes to the API via `skulk notes sync`.
- *              Supports human + JSON output modes; JSON mode is stdout-pure.
- */
-import { Command } from 'commander';
-import { SKULK_BASE_URL, SKULK_TOKEN } from '../lib/config.js';
-import { httpJson } from '../lib/http.js';
-import { listMarkdownFiles, readNote } from '../lib/notes.js';
-import { getOutputMode, printJson } from '../cli/output.js';
-import { buildSyncReport } from '../cli/outputContract.js';
-import fs from 'node:fs';
-async function upsertNote(baseUrl, token, note, locale) {
-    const payload = {
-        slug: note.slug,
-        title: note.attributes.title,
-        markdown: note.markdown,
-        locale,
-    };
-    if (!payload.slug || !payload.title || !payload.markdown) {
-        throw new Error(`Invalid note payload: slug/title/markdown missing for ${payload.slug ?? 'unknown'}`);
-    }
-    return httpJson({ baseUrl, token }, 'POST', '/lab-notes/upsert', payload);
-}
-export function notesSyncCommand() {
-    const notes = new Command('notes').description('Lab Notes commands');
-    notes
-        .command('sync')
-        .description('Sync local markdown notes to the API')
-        .option('--dir <path>', 'Directory containing markdown notes', './src/labnotes/en')
-        //.option("--dir <path>", "Directory containing markdown notes", "./labnotes/en")
-        .option('--locale <code>', 'Locale code', 'en')
-        .option('--base-url <url>', 'Override API base URL (ex: https://api.thehumanpatternlab.com)')
-        .option('--dry-run', 'Print what would be sent, but do not call the API', false)
-        .option('--only <slug>', 'Sync only a single note by slug')
-        .option('--limit <n>', 'Sync only the first N notes', (v) => parseInt(v, 10))
-        .action(async (opts, cmd) => {
-        const mode = getOutputMode(cmd); // "json" | "human"
-        const jsonError = (message, extra) => {
-            if (mode === 'json') {
-                process.stderr.write(JSON.stringify({ ok: false, error: { message, extra } }, null, 2) +
-                    '\n');
-            }
-            else {
-                console.error(message);
-                if (extra)
-                    console.error(extra);
-            }
-            process.exitCode = 1;
-        };
-        if (!fs.existsSync(opts.dir)) {
-            jsonError(`Notes directory not found: ${opts.dir}`, {
-                hint: `Try: skulk notes sync --dir "..\\\\the-human-pattern-lab\\\\src\\\\labnotes\\\\en"`,
-            });
-            return;
-        }
-        const baseUrl = SKULK_BASE_URL(opts.baseUrl);
-        const token = SKULK_TOKEN();
-        const files = listMarkdownFiles(opts.dir);
-        let selectedFiles = files;
-        if (opts.only) {
-            selectedFiles = files.filter((f) => f.toLowerCase().includes(opts.only.toLowerCase()));
-        }
-        if (opts.limit && Number.isFinite(opts.limit)) {
-            selectedFiles = selectedFiles.slice(0, opts.limit);
-        }
-        if (selectedFiles.length === 0) {
-            if (mode === 'json') {
-                printJson({
-                    ok: true,
-                    action: 'noop',
-                    message: 'No matching notes found.',
-                    matched: 0,
-                });
-            }
-            else {
-                console.log('No matching notes found.');
-            }
-            process.exitCode = 0;
-            return;
-        }
-        // Human-mode header chatter
-        if (mode === 'human') {
-            console.log(`Skulk syncing ${selectedFiles.length} note(s) from ${opts.dir}`);
-            console.log(`API: ${baseUrl}`);
-            console.log(`Locale: ${opts.locale}`);
-            console.log(opts.dryRun ? 'Mode: DRY RUN (no writes)' : 'Mode: LIVE (writing)');
-        }
-        let ok = 0;
-        let fail = 0;
-        const results = [];
-        for (const file of selectedFiles) {
-            try {
-                const note = readNote(file, opts.locale);
-                if (opts.dryRun) {
-                    ok++;
-                    results.push({
-                        file,
-                        slug: note.slug,
-                        status: 'dry-run',
-                    });
-                    if (mode === 'human') {
-                        console.log(`\n---\n${note.slug}\n${file}\nfrontmatter keys: ${Object.keys(note.attributes).join(', ')}`);
-                    }
-                    continue;
-                }
-                const res = await upsertNote(baseUrl, token, note, opts.locale);
-                ok++;
-                results.push({
-                    file,
-                    slug: note.slug,
-                    status: 'ok',
-                    action: res.action,
-                });
-                if (mode === 'human') {
-                    console.log(`✅ ${note.slug} (${res.action ?? 'ok'})`);
-                }
-            }
-            catch (e) {
-                fail++;
-                const msg = String(e);
-                results.push({
-                    file,
-                    status: 'fail',
-                    error: msg,
-                });
-                if (mode === 'human') {
-                    console.error(`❌ ${file}`);
-                    console.error(msg);
-                }
-            }
-        }
-        if (mode === 'json') {
-            const report = buildSyncReport({
-                results,
-                dryRun: Boolean(opts.dryRun),
-                locale: opts.locale,
-                baseUrl,
-            });
-            printJson(report);
-            if (!report.ok)
-                process.exitCode = 1;
-        }
-        else {
-            const report = buildSyncReport({
-                results,
-                dryRun: Boolean(opts.dryRun),
-                locale: opts.locale,
-                baseUrl,
-            });
-            const { synced, dryRun, failed } = report.summary;
-            if (report.dryRun) {
-                console.log(`\nDone. ${dryRun} note(s) would be synced (dry-run). Failures: ${failed}`);
-            }
-            else {
-                console.log(`\nDone. ${synced} note(s) synced successfully. Failures: ${failed}`);
-            }
-            if (!report.ok)
-                process.exitCode = 1;
-        }
-    });
-    return notes;
-}

package/dist/sync/summary.js

@@ -1,25 +0,0 @@
-export function buildSyncSummary(results, dryRunMode) {
-    let synced = 0;
-    let dryRun = 0;
-    let failed = 0;
-    for (const r of results) {
-        if (r.status === "failed") {
-            failed++;
-            continue;
-        }
-        if (dryRunMode)
-            dryRun++;
-        else
-            synced++;
-    }
-    const total = results.length;
-    // Invariant: dry-run must never report synced writes
-    if (dryRunMode && synced > 0) {
-        throw new Error("Invariant violation: dry-run mode cannot produce synced > 0");
-    }
-    // Invariant: accounting must balance
-    if (synced + dryRun + failed !== total) {
-        throw new Error("SyncSummary invariant failed: counts do not add up to total");
-    }
-    return { synced, dryRun, failed, total };
-}

package/dist/sync/types.js

@@ -1,2 +0,0 @@
-// src/sync/types.ts
-export {};

package/dist/utils/loadMarkdown.js

@@ -1,10 +0,0 @@
-import fs from 'fs';
-import matter from 'gray-matter';
-export function loadMarkdown(filePath) {
-    const raw = fs.readFileSync(filePath, 'utf8');
-    const parsed = matter(raw);
-    return {
-        content: parsed.content.trim(),
-        metadata: parsed.data
-    };
-}