@thehumanpatternlab/skulk 0.1.1

package/README.md

@@ -0,0 +1,115 @@
+<!--
+  Skulk CLI
+  The Human Pattern Lab
+
+  This README is written for humans.
+  Design rationale lives in DESIGN.md.
+-->
+# Skulk CLI
+
+[![AI-Forward CLI](https://img.shields.io/badge/AI--Forward%20CLI-automation--safe%20by%20design-7c3aed?style=flat-square)](./DESIGN.md) ![Carmel Judgment](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg)
+
+
+
+> A modern, automation-safe CLI for The Human Pattern Lab.
+
+Skulk is a command-line tool for syncing and managing Lab Notes — built to work just as well for humans at the keyboard as it does for automation, CI, and agent-driven workflows.
+
+---
+## What Skulk Connects To
+
+Skulk is the CLI for **The Human Pattern Lab API**.
+
+By default it targets a Human Pattern Lab API instance. You can override the API endpoint with `--base-url` to use staging or a self-hosted deployment of the same API.
+
+> Note: `--base-url` is intended for alternate deployments of the Human Pattern Lab API, not arbitrary third-party APIs.
+
+---
+## Configuration
+
+### Environment variables
+
+- `SKULK_TOKEN` — API token used to authenticate requests.
+- `SKULK_BASE_URL` — Base URL for a Human Pattern Lab API instance (overridden by `--base-url`).
+
+Example:
+
+```bash
+export SKULK_TOKEN="..."
+export SKULK_BASE_URL="https://thehumanpatternlab.com/api"
+skulk notes sync --dir ./src/labnotes/en
+```
+---
+
+## Why Skulk Exists
+
+Command-line tools no longer live in a human-only world.
+
+They’re run by:
+- developers exploring and iterating
+- scripts and CI pipelines
+- automation layers and AI-assisted workflows
+
+Skulk was designed from the start to behave **predictably and honestly** in all of those contexts — without sacrificing human usability.
+
+---
+
+## 🤖 AI-Forward (for Humans)
+
+Skulk follows **AI-forward engineering principles** — not for AIs, but for the people who build tools that increasingly interact with them.
+
+### Dual Output Modes
+
+By default, Skulk is human-readable:
+
+```bash
+skulk notes sync
+```
+
+When `--json` is enabled:
+
+```bash
+skulk --json notes sync
+```
+
+Skulk switches to machine-readable output:
+- stdout contains **only valid JSON**
+- no banners, emojis, or progress chatter
+- errors go to stderr
+- exit codes are deterministic
+
+This makes Skulk safe to use in:
+- scripts
+- CI pipelines
+- automation
+- AI-assisted workflows
+
+---
+
+## JSON Output Contract
+
+Structured output is treated as a **contract**, not a courtesy.
+
+The repository includes a built-in verification:
+
+```bash
+npm run json:check
+```
+
+This command runs Skulk in `--json` mode and fails immediately if *any* non-JSON output appears on stdout.
+
+---
+
+## Design & Philosophy
+
+Curious why Skulk works this way?  
+→ [DESIGN.md](./DESIGN.md)
+
+---
+
+## Philosophy
+
+> Automation shouldn’t require guessing what a tool *meant* to say.
+
+Skulk is boring in the best way:
+predictable, explicit, and dependable.

package/dist/cli/output.js

@@ -0,0 +1,21 @@
+// 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

@@ -0,0 +1,32 @@
+// 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

@@ -0,0 +1,191 @@
+/* ===========================================================
+   🦊 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/index.js

@@ -0,0 +1,36 @@
+#!/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/lib/config.js

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,62 @@
+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/sdk/LabClient.js

@@ -0,0 +1,94 @@
+// 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/sync/summary.js

@@ -0,0 +1,25 @@
+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

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

package/dist/utils/loadMarkdown.js

@@ -0,0 +1,10 @@
+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
+    };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@thehumanpatternlab/skulk",
+  "version": "0.1.1",
+  "private": false,
+  "description": "CLI for syncing Lab Notes with The Human Pattern Lab API",
+  "keywords": [
+    "cli",
+    "automation",
+    "human-pattern-lab"
+  ],
+  "author": "Ada Vale",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "skulk": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/lab.js",
+    "dist/cli/**",
+    "dist/commands/**",
+    "dist/lib/**",
+    "dist/sdk/**",
+    "dist/sync/**",
+    "dist/utils/**"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "build:watch": "tsc -w",
+    "json:check": "skulk --json notes sync --dry-run --dir \"../the-human-pattern-lab/src/labnotes/en\" | node -e \"JSON.parse(require('fs').readFileSync(0,'utf8')); console.log('JSON output is clean ✅')\"",
+    "json:check:pretty": "npm run json:check && echo \"JSON output is clean ✅\"",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest watch",
+    "link": "npm run build && npm link"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "gray-matter": "^4.0.3",
+    "node-fetch": "^3.3.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.16",
+    "typescript": "^5.9.3"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.{js,ts,md,json}": "prettier --write"
+  }
+}