@thehumanpatternlab/hpl 0.0.1-alpha.5

package/dist/src/config.js

@@ -0,0 +1,10 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI CONFIG
+   -----------------------------------------------------------
+   Purpose: Single source of truth for config resolution.
+   Contract: Deterministic defaults.
+   =========================================================== */
+export function getConfig() {
+    const apiBaseUrl = (process.env.HPL_API_BASE_URL || "https://api.thehumanpatternlab.com").replace(/\/+$/, "");
+    return { apiBaseUrl };
+}

package/dist/src/contract/capabilities.js

@@ -0,0 +1,15 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI CAPABILITIES (Alpha Tier)
+   -----------------------------------------------------------
+   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";
+export function getCapabilitiesAlpha() {
+    return {
+        intentTier: "alpha",
+        supportedIntents: listAlphaIntents().map((i) => i.intent),
+        schemaVersions: [CLI_SCHEMA_VERSION],
+    };
+}

package/dist/src/contract/envelope.js

@@ -0,0 +1,16 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI ENVELOPE BUILDERS (Alpha Tier)
+   -----------------------------------------------------------
+   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";
+export function ok(command, intent, data) {
+    return { schemaVersion: CLI_SCHEMA_VERSION, command, status: "ok", intent, data };
+}
+export function warn(command, intent, warnings, data) {
+    return { schemaVersion: CLI_SCHEMA_VERSION, command, status: "warn", intent, warnings, data };
+}
+export function err(command, intent, error) {
+    return { schemaVersion: CLI_SCHEMA_VERSION, command, status: "error", intent, error };
+}

package/dist/src/contract/exitCodes.js

@@ -0,0 +1,21 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI EXIT CODES (Alpha Tier)
+   -----------------------------------------------------------
+   Purpose: Consistent meanings across commands (machine-parseable).
+   Contract: "Errors & Exit Codes" predictable and structured.
+   =========================================================== */
+/**
+ * Exit code meanings are stable across commands.
+ * Additive only; do not repurpose existing numeric values.
+ */
+export const EXIT = {
+    OK: 0,
+    USAGE: 2, // bad args / invalid flags
+    NOT_FOUND: 3, // 404 semantics
+    AUTH: 4, // auth required / invalid token
+    FORBIDDEN: 5, // insufficient scope/permission
+    NETWORK: 10, // DNS/timeout/unreachable
+    SERVER: 11, // 5xx or unexpected response
+    CONTRACT: 12, // schema mismatch / invalid JSON contract
+    UNKNOWN: 1,
+};

package/dist/src/contract/intents.js

@@ -0,0 +1,49 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI INTENT REGISTRY (Alpha Tier)
+   -----------------------------------------------------------
+   Purpose: Machine-legible, stable intent identifiers for CLI commands.
+   Contract: Lab CLI MVP Contract v0.x (Intent Registry + Explicit Intent)
+   Notes:
+     - Intent IDs are snake_case and treated as contractual identifiers.
+     - Changing the meaning of an intent is breaking, even in v0.x.
+   =========================================================== */
+/**
+ * Alpha Tier intents (MVP).
+ * Additive only. Do not change semantics of existing IDs.
+ */
+export const INTENTS_ALPHA = {
+    show_version: {
+        intent: "show_version",
+        intentVersion: "1",
+        scope: ["cli"],
+        sideEffects: [],
+        reversible: true,
+    },
+    show_capabilities: {
+        intent: "show_capabilities",
+        intentVersion: "1",
+        scope: ["cli"],
+        sideEffects: [],
+        reversible: true,
+    },
+    check_health: {
+        intent: "check_health",
+        intentVersion: "1",
+        scope: ["remote_api"],
+        sideEffects: [],
+        reversible: true,
+    },
+    render_lab_note: {
+        intent: "render_lab_note",
+        intentVersion: "1",
+        scope: ["lab_notes", "remote_api"],
+        sideEffects: [],
+        reversible: true,
+    },
+};
+export function getAlphaIntent(id) {
+    return INTENTS_ALPHA[id];
+}
+export function listAlphaIntents() {
+    return Object.values(INTENTS_ALPHA);
+}

package/dist/src/contract/schema.js

@@ -0,0 +1,59 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI OUTPUT SCHEMAS (Alpha Tier)
+   -----------------------------------------------------------
+   Purpose: Enforce the "JSON is a Contract" guarantee for --json mode.
+   Contract: Lab CLI MVP Contract v0.x (Schema Versioning + Determinism)
+   =========================================================== */
+import { z } from "zod";
+/** Global structured output schema version (CLI contract layer). */
+export const CLI_SCHEMA_VERSION = "0.1";
+export const StatusSchema = z.enum(["ok", "warn", "error"]);
+export const IntentBlockSchema = z.object({
+    intent: z.string(),
+    intentVersion: z.literal("1"),
+    scope: z.array(z.string()),
+    sideEffects: z.array(z.string()),
+    reversible: z.boolean(),
+});
+/**
+ * Base envelope required by the contract for all --json outputs.
+ * Commands extend this with typed `data` for success, or `error` for failures.
+ */
+export const BaseEnvelopeSchema = z.object({
+    schemaVersion: z.literal(CLI_SCHEMA_VERSION),
+    command: z.string(),
+    status: StatusSchema,
+    intent: IntentBlockSchema,
+});
+/** Standard error payload (machine-parseable). */
+export const ErrorPayloadSchema = z.object({
+    code: z.string(), // stable error code (e.g., "E_NETWORK", "E_AUTH")
+    message: z.string(), // short human-readable
+    details: z.unknown().optional() // optional machine-parseable context
+});
+/**
+ * Success envelope: { ...base, data: T }
+ */
+export function successSchema(dataSchema) {
+    return BaseEnvelopeSchema.extend({
+        status: z.literal("ok"),
+        data: dataSchema,
+    });
+}
+/**
+ * Warning envelope: { ...base, warnings: [...], data?: T }
+ */
+export function warnSchema(dataSchema) {
+    const base = BaseEnvelopeSchema.extend({
+        status: z.literal("warn"),
+        warnings: z.array(z.string()).min(1),
+    });
+    return dataSchema ? base.extend({ data: dataSchema }) : base;
+}
+/**
+ * Error envelope: { ...base, error: { code, message, details? } }
+ */
+export const ErrorEnvelopeSchema = BaseEnvelopeSchema.extend({
+    status: z.literal("error"),
+    error: ErrorPayloadSchema,
+});

package/dist/src/http/client.js

@@ -0,0 +1,39 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — HTTP CLIENT (minimal)
+   -----------------------------------------------------------
+   Purpose: Fetch wrapper with consistent error shaping.
+   Notes:
+     - Supports both raw API payloads and envelope form { ok: true, data: ... }.
+   =========================================================== */
+import { getConfig } from "../config";
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+function unwrap(payload) {
+    if (payload && typeof payload === "object" && payload.ok === true) {
+        return payload.data;
+    }
+    return payload;
+}
+export async function getJson(path, signal) {
+    const { apiBaseUrl } = getConfig();
+    const url = apiBaseUrl + path;
+    const res = await fetch(url, { method: "GET", signal });
+    if (!res.ok) {
+        let body = "";
+        try {
+            body = await res.text();
+        }
+        catch { /* ignore */ }
+        throw new HttpError(`GET ${path} failed`, res.status, body);
+    }
+    const payload = (await res.json());
+    return unwrap(payload);
+}

package/dist/src/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/src/io.js

@@ -0,0 +1,15 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — CLI IO GATE
+   -----------------------------------------------------------
+   Purpose: Enforce "--json means JSON only on stdout".
+   =========================================================== */
+export function writeJson(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+export function writeHuman(text) {
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+}
+/** Logs to stderr only. Safe to call even in --json mode (but we avoid it by policy). */
+export function logErr(message) {
+    process.stderr.write(message.endsWith("\n") ? message : message + "\n");
+}

package/dist/src/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/src/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/src/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/src/render/table.js

@@ -0,0 +1,17 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — TABLE RENDERER (tiny)
+   -----------------------------------------------------------
+   Purpose: Deterministic fixed-width table output.
+   =========================================================== */
+function pad(s, width) {
+    const str = (s ?? "").toString();
+    if (str.length >= width)
+        return str.slice(0, Math.max(0, width - 1)) + "…";
+    return str + " ".repeat(width - str.length);
+}
+export function renderTable(rows, cols) {
+    const header = cols.map((c) => pad(c.header, c.width)).join("  ");
+    const sep = cols.map((c) => "-".repeat(c.width)).join("  ");
+    const body = rows.map((r) => cols.map((c) => pad(c.value(r), c.width)).join("  ")).join("\n");
+    return [header, sep, body].filter(Boolean).join("\n");
+}

package/dist/src/render/text.js

@@ -0,0 +1,40 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — TEXT RENDER UTILS
+   -----------------------------------------------------------
+   Purpose: Deterministic, dependency-free formatting for terminals.
+   =========================================================== */
+export function stripHtml(input) {
+    const s = (input || "");
+    // Convert common structure to deterministic newlines first
+    const withBreaks = s
+        .replace(/<\s*br\s*\/?>/gi, "\n")
+        .replace(/<\/\s*p\s*>/gi, "\n\n")
+        .replace(/<\s*p[^>]*>/gi, "")
+        .replace(/<\s*hr\s*\/?>/gi, "\n---\n")
+        .replace(/<\/\s*li\s*>/gi, "\n")
+        .replace(/<\s*li[^>]*>/gi, "- ")
+        .replace(/<\/\s*ul\s*>/gi, "\n")
+        .replace(/<\s*ul[^>]*>/gi, "");
+    // Strip scripts/styles then remaining tags
+    const stripped = withBreaks
+        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
+        .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, "")
+        .replace(/<[^>]+>/g, "");
+    // Decode a few entities + normalize whitespace
+    return stripped
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/\r\n/g, "\n")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+export function safeLine(s) {
+    return (s ?? "").replace(/\s+/g, " ").trim();
+}
+export function formatTags(tags) {
+    const t = (tags ?? []).filter(Boolean);
+    return t.length ? t.join(", ") : "-";
+}

package/dist/src/sdk/ApiError.js

@@ -0,0 +1,10 @@
+export class ApiError extends Error {
+    status;
+    payload;
+    constructor(message, status, payload) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.payload = payload;
+    }
+}

package/dist/src/sdk/LabClient.js

@@ -0,0 +1,101 @@
+// src/sdk/LabClient.ts
+export class LabClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        // baseUrl should be like: https://api.thehumanpatternlab.com
+        // (no trailing slash, no /api)
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.token = token;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    buildHeaders(extra, auth = "none") {
+        const h = { ...(extra ?? {}) };
+        // Only set JSON content-type when we actually send a JSON body
+        // (some servers get weird on GETs with Content-Type set)
+        if (!h["Content-Type"])
+            h["Content-Type"] = "application/json";
+        if (auth === "bearer" && this.token) {
+            h["Authorization"] = `Bearer ${this.token}`;
+        }
+        return h;
+    }
+    async request(path, opts = {}) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+        const auth = opts.auth ?? "none";
+        const headers = this.buildHeaders(opts.headers, auth);
+        const res = await fetch(url, {
+            ...opts,
+            headers,
+            credentials: auth === "cookie" ? "include" : opts.credentials,
+        });
+        // Best-effort parse
+        const payload = await res.json().catch(() => null);
+        if (!res.ok) {
+            const msg = typeof payload === "object" &&
+                payload !== null &&
+                ("error" in payload || "message" in payload) &&
+                typeof payload.error === "string"
+                ? payload.error
+                : typeof payload?.message === "string"
+                    ? payload.message
+                    : `Request failed (${res.status})`;
+            throw new Error(msg);
+        }
+        return payload;
+    }
+    //
+    // ────────────────────────────────────────────────
+    //   PUBLIC ROUTES
+    // ────────────────────────────────────────────────
+    //
+    // ✅ was GET `${baseUrl}/`
+    async getAllNotes() {
+        return this.request("/lab-notes", { method: "GET", auth: "none" });
+    }
+    // ✅ was GET `${baseUrl}/notes/${slug}`
+    async getNoteBySlug(slug) {
+        return this.request(`/lab-notes/${encodeURIComponent(slug)}`, {
+            method: "GET",
+            auth: "none",
+        });
+    }
+    //
+    // ────────────────────────────────────────────────
+    //   ADMIN ROUTES
+    // ────────────────────────────────────────────────
+    //
+    // ✅ was `/api/admin/notes`
+    async getAdminNotes() {
+        return this.request("/admin/notes", {
+            method: "GET",
+            auth: "cookie",
+        });
+    }
+    // ✅ was `/api/admin/notes`
+    async createOrUpdateNote(input) {
+        return this.request("/admin/notes", {
+            method: "POST",
+            auth: "cookie",
+            body: JSON.stringify(input),
+        });
+    }
+    // ✅ was `/api/admin/notes/${id}`
+    async deleteNote(id) {
+        return this.request(`/admin/notes/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+            auth: "cookie",
+        });
+    }
+    //
+    // ────────────────────────────────────────────────
+    //   HEALTH
+    // ────────────────────────────────────────────────
+    //
+    // ✅ was `/api/health`
+    async health() {
+        return this.request("/health", { method: "GET", auth: "none" });
+    }
+}

package/dist/src/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/src/sync/types.js

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

package/dist/src/types/labNotes.js

@@ -0,0 +1,27 @@
+/* ===========================================================
+   🌌 HUMAN PATTERN LAB — TYPES: Lab Notes (CLI)
+   -----------------------------------------------------------
+   Purpose: API contract types for Lab Notes used by the CLI.
+   Notes:
+     - Keep permissive: API may add fields (additive).
+   =========================================================== */
+import { z } from "zod";
+export const LabNoteSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    summary: z.string().optional().default(""),
+    contentHtml: z.string().optional().default(""),
+    published: z.string().optional().nullable(),
+    status: z.string().optional(),
+    type: z.string().optional(),
+    locale: z.string().optional(),
+    department_id: z.string().optional(),
+    shadow_density: z.number().optional(),
+    safer_landing: z.boolean().optional(),
+    tags: z.array(z.string()).optional().default([]),
+    readingTime: z.number().optional(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+}).passthrough();
+export const LabNoteListSchema = z.array(LabNoteSchema);

package/dist/src/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
+    };
+}