@thehumanpatternlab/hpl 0.0.1-alpha.5 → 1.0.0

package/dist/src/commands/version.js

@@ -1,11 +1,28 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: version
    =========================================================== */
+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";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
+export function versionCommand() {
+    return new Command("version")
+        .description("Show CLI version (contract: show_version)")
+        .action((...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const envelope = runVersion("version");
+        if (rootOpts.json)
+            writeJson(envelope);
+        else
+            writeHuman(`${envelope.data?.name} ${envelope.data?.version}`.trim());
+        process.exitCode = EXIT.OK;
+    });
+}
 export function runVersion(commandName = "version") {
     const intent = getAlphaIntent("show_version");
     return ok(commandName, intent, { name: pkg.name, version: pkg.version });

package/dist/src/contract/exitCodes.js

@@ -14,6 +14,8 @@ export const EXIT = {
     NOT_FOUND: 3, // 404 semantics
     AUTH: 4, // auth required / invalid token
     FORBIDDEN: 5, // insufficient scope/permission
+    VALIDATION: 6, // data validation failed
+    IO: 7, // file I/O errors
     NETWORK: 10, // DNS/timeout/unreachable
     SERVER: 11, // 5xx or unexpected response
     CONTRACT: 12, // schema mismatch / invalid JSON contract

package/dist/src/contract/intents.js

@@ -40,6 +40,20 @@ export const INTENTS_ALPHA = {
         sideEffects: [],
         reversible: true,
     },
+    create_lab_note: {
+        intent: "create_lab_note",
+        intentVersion: "1",
+        scope: ["lab_notes", "remote_api"],
+        sideEffects: ["write_remote"],
+        reversible: false,
+    },
+    update_lab_note: {
+        intent: "update_lab_note",
+        intentVersion: "1",
+        scope: ["lab_notes", "remote_api"],
+        sideEffects: ["write_remote"],
+        reversible: false,
+    },
 };
 export function getAlphaIntent(id) {
     return INTENTS_ALPHA[id];

package/dist/src/http/client.js

@@ -37,3 +37,29 @@ export async function getJson(path, signal) {
     const payload = (await res.json());
     return unwrap(payload);
 }
+export async function postJson(path, body, token, signal) {
+    const { apiBaseUrl } = getConfig();
+    const url = apiBaseUrl + path;
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (token) {
+        headers["Authorization"] = `Bearer ${token}`;
+    }
+    const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!res.ok) {
+        let responseBody = "";
+        try {
+            responseBody = await res.text();
+        }
+        catch { /* ignore */ }
+        throw new HttpError(`POST ${path} failed`, res.status, responseBody);
+    }
+    const payload = (await res.json());
+    return unwrap(payload);
+}

package/dist/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /* ===========================================================
-   🦊 THE HUMAN PATTERN LAB — SKULK CLI
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
    -----------------------------------------------------------
    File: notesSync.ts
    Role: Command Implementation
@@ -8,7 +8,7 @@
    Assistant: Lyric
    Status: Active
    Description:
-     Implements the `skulk notes sync` command.
+     Implements the `hpl notes sync` command.
      Handles human-readable and machine-readable output modes
      with enforced JSON purity for automation safety.
    -----------------------------------------------------------
@@ -19,18 +19,19 @@
      - Exit codes are deterministic
    =========================================================== */
 import { Command } from "commander";
-import { notesSyncCommand } from "./commands/notesSync.js";
+import { notesSyncSubcommand } from "./commands/notes/notesSync.js";
 const program = new Command();
 program
-    .name("skulk")
-    .description("Skulk CLI for The Human Pattern Lab")
+    .name("hpl")
+    .description("Human Pattern Lab CLI (alpha)")
     .version("0.1.0")
-    .option("--json", "Output machine-readable JSON")
+    .option("--json", "Emit contract JSON only on stdout")
     .configureHelp({ helpWidth: 100 });
 const argv = process.argv.slice(2);
 if (argv.length === 0) {
     program.outputHelp();
     process.exit(0);
 }
-program.addCommand(notesSyncCommand());
+// Mount domains
+program.addCommand(notesSyncSubcommand());
 program.parse(process.argv);

package/dist/src/lib/config.js

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

package/dist/src/lib/contentRepo.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execa } from "execa";
+function normalizeRepoUrl(repo) {
+    const raw = repo.trim();
+    if (raw.startsWith("http://") || raw.startsWith("https://") || raw.startsWith("git@"))
+        return raw;
+    return `https://github.com/${raw}.git`;
+}
+function safeRepoKey(repo) {
+    // stable-ish folder name for owner/name or URL
+    return repo.trim().replace(/[^a-z0-9._-]+/gi, "_").toLowerCase();
+}
+function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+async function runGit(args, opts = {}) {
+    const p = execa("git", args, {
+        cwd: opts.cwd,
+        // Avoid stdout pollution when in --json mode (or any strict mode).
+        stdio: opts.quietStdout ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (opts.quietStdout) {
+        p.stdout?.on("data", (d) => process.stderr.write(d));
+        p.stderr?.on("data", (d) => process.stderr.write(d));
+    }
+    return await p;
+}
+export async function resolveContentRepo({ repo, ref = "main", cacheDir, quietStdout = false, }) {
+    const repoUrl = normalizeRepoUrl(repo);
+    const base = cacheDir ?? path.join(os.homedir(), ".hpl", "cache", "content");
+    const dir = path.join(base, safeRepoKey(repo));
+    ensureDir(base);
+    const gitDir = path.join(dir, ".git");
+    const exists = fs.existsSync(gitDir);
+    if (!exists) {
+        ensureDir(dir);
+        // Clone shallow if branch-like ref; if ref is a sha, shallow clone won’t help much.
+        await runGit(["clone", "--depth", "1", "--branch", ref, repoUrl, dir], { quietStdout });
+    }
+    else {
+        // Keep it predictable: fetch + checkout + ff-only pull.
+        await runGit(["-C", dir, "fetch", "--all", "--tags", "--prune"], { quietStdout });
+        await runGit(["-C", dir, "checkout", ref], { quietStdout });
+        await runGit(["-C", dir, "pull", "--ff-only"], { quietStdout });
+    }
+    return { dir, repoUrl, ref };
+}

package/dist/src/render/table.js

@@ -3,6 +3,13 @@
    -----------------------------------------------------------
    Purpose: Deterministic fixed-width table output.
    =========================================================== */
+export function safeLine(s) {
+    return (s ?? "").replace(/\s+/g, " ").trim();
+}
+export function formatTags(tags) {
+    const t = (tags ?? []).filter(Boolean);
+    return t.length ? t.join(", ") : "-";
+}
 function pad(s, width) {
     const str = (s ?? "").toString();
     if (str.length >= width)

package/dist/src/render/text.js

@@ -1,8 +1,4 @@
-/* ===========================================================
-   🌌 HUMAN PATTERN LAB — TEXT RENDER UTILS
-   -----------------------------------------------------------
-   Purpose: Deterministic, dependency-free formatting for terminals.
-   =========================================================== */
+import { formatTags, safeLine } from "./table";
 export function stripHtml(input) {
     const s = (input || "");
     // Convert common structure to deterministic newlines first
@@ -31,10 +27,72 @@ export function stripHtml(input) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
-export function safeLine(s) {
-    return (s ?? "").replace(/\s+/g, " ").trim();
+function renderError(env) {
+    console.error(`✖ ${env.command}`);
+    if (env.error?.message) {
+        console.error(safeLine(env.error.message));
+    }
+    if (env.error?.details) {
+        console.error();
+        console.error(stripHtml(String(env.error.details)));
+    }
 }
-export function formatTags(tags) {
-    const t = (tags ?? []).filter(Boolean);
-    return t.length ? t.join(", ") : "-";
+function renderWarn(env) {
+    console.log(`⚠ ${env.command}`);
+    for (const w of env.warnings ?? []) {
+        console.log(`- ${safeLine(w)}`);
+    }
+    if (env.data !== undefined) {
+        console.log();
+        renderData(env.data);
+    }
+}
+function renderSuccess(env) {
+    renderData(env.data);
+}
+function renderData(data) {
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            renderItem(item);
+            console.log();
+        }
+        return;
+    }
+    if (typeof data === "object" && data !== null) {
+        renderItem(data);
+        return;
+    }
+    console.log(String(data));
+}
+function renderItem(note) {
+    if (note.title) {
+        console.log(safeLine(note.title));
+    }
+    if (note.subtitle) {
+        console.log(`  ${safeLine(note.subtitle)}`);
+    }
+    if (note.summary || note.excerpt) {
+        console.log();
+        console.log(stripHtml(note.summary ?? note.excerpt));
+    }
+    if (note.tags) {
+        console.log();
+        console.log(`Tags: ${formatTags(note.tags)}`);
+    }
+}
+export function renderText(envelope) {
+    switch (envelope.status) {
+        case "error":
+            renderError(envelope);
+            return;
+        case "warn":
+            renderWarn(envelope);
+            return;
+        case "ok":
+            renderSuccess(envelope);
+            return;
+        default:
+            // Exhaustiveness guard
+            console.error("Unknown envelope status");
+    }
 }

package/dist/src/types/labNotes.js

@@ -5,23 +5,107 @@
    Notes:
      - Keep permissive: API may add fields (additive).
    =========================================================== */
+// - GET /lab-notes         -> LabNotePreview[]
+// - GET /lab-notes/:slug   -> LabNoteDetail (LabNoteView + content_markdown)
 import { z } from "zod";
-export const LabNoteSchema = z.object({
+/** Mirrors API LabNoteType */
+export const LabNoteTypeSchema = z.enum(["labnote", "paper", "memo", "lore", "weather"]);
+/** Mirrors API LabNoteStatus */
+export const LabNoteStatusSchema = z.enum(["published", "draft", "archived"]);
+export const ALLOWED_NOTE_TYPES = new Set([
+    "labnote",
+    "paper",
+    "memo",
+    "lore",
+    "weather",
+]);
+/**
+ * GET /lab-notes (list)
+ * You are selecting from v_lab_notes without content_html/markdown,
+ * then mapping via mapToLabNotePreview(...).
+ *
+ * We infer likely fields from the SELECT + typical preview mapper.
+ * Keep passthrough to allow additive changes.
+ */
+export const LabNotePreviewSchema = 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(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    excerpt: z.string().optional(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
     locale: z.string().optional(),
-    department_id: z.string().optional(),
+    department_id: z.string().optional(), // DB has it; mapper may include it
     shadow_density: z.number().optional(),
-    safer_landing: z.boolean().optional(),
-    tags: z.array(z.string()).optional().default([]),
-    readingTime: z.number().optional(),
+    safer_landing: z.boolean().optional(), // DB is number-ish; mapper likely coerces
+    readingTime: z.number().optional(), // from read_time_minutes
+    published: z.string().optional(), // from published_at (if mapper emits it)
     created_at: z.string().optional(),
     updated_at: z.string().optional(),
-}).passthrough();
-export const LabNoteListSchema = z.array(LabNoteSchema);
+    tags: z.array(z.string()).optional(), // mapper adds tags
+})
+    .passthrough();
+export const LabNotePreviewListSchema = z.array(LabNotePreviewSchema);
+/**
+ * API LabNoteView shape (detail rendering fields).
+ * This aligns to your LabNoteView interface.
+ */
+export const LabNoteViewSchema = z
+    .object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    // NOTE: contentHtml intentionally excluded.
+    // Markdown is the canonical source of truth for CLI clients.
+    published: z.string(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
+    locale: z.string().optional(),
+    author: z
+        .object({
+        kind: z.enum(["human", "ai", "hybrid"]),
+        name: z.string().optional(),
+        id: z.string().optional(),
+    })
+        .optional(),
+    department_id: z.string(),
+    shadow_density: z.number(),
+    safer_landing: z.boolean(),
+    tags: z.array(z.string()),
+    readingTime: z.number(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+})
+    .passthrough();
+/**
+ * GET /lab-notes/:slug returns LabNoteView + content_markdown (canonical truth).
+ */
+export const LabNoteDetailSchema = LabNoteViewSchema.extend({
+    content_markdown: z.string().optional(), // API always includes it in your code, but keep optional for safety
+});
+/**
+ * CLI → API payload for upsert (notes sync).
+ * Strict: our outbound contract.
+ */
+export const LabNoteUpsertSchema = z
+    .object({
+    slug: z.string().min(1),
+    title: z.string().min(1),
+    markdown: z.string().min(1),
+    locale: z.string().optional(),
+    subtitle: z.string().optional(),
+    summary: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    published: z.string().optional(),
+    status: LabNoteStatusSchema.optional(),
+    type: LabNoteTypeSchema.optional(),
+    dept: z.string().optional(),
+})
+    .strict();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehumanpatternlab/hpl",
-  "version": "0.0.1-alpha.5",
+  "version": "1.0.0",
   "description": "AI-forward, automation-safe SDK and CLI for the Human Pattern Lab",
   "type": "module",
   "license": "MIT",
@@ -37,10 +37,12 @@
     "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"
   },