@thehumanpatternlab/hpl 0.0.1-alpha.5 → 1.0.0

package/README.md

@@ -1,42 +1,182 @@
-# HPL CLI (Alpha) 🧭🦊
-
-<span>
-  <img src="https://img.shields.io/badge/AI--Forward%20CLI-black?style=flat-square" />
-  <img src="https://img.shields.io/badge/automation--safe%20by%20design-8b5cf6?style=flat-square" />
-</span>
- 
- [![Carmel Judgment Protocol 😼](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg)](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml)
-
-Contract-first CLI for The Human Pattern Lab.
-
-## Install (local dev)
-
-```bash
-npm install
-npm run dev -- --help
-```
-
-## Config
-
-- `HPL_API_BASE_URL` (default: `https://api.thehumanpatternlab.com`)
-
-## Commands (MVP)
-
-- `hpl version`
-- `hpl capabilities`
-- `hpl health`
-- `hpl notes list [--limit N]`
-- `hpl notes get <slug> [--raw]`
-
-## JSON contract
-
-Add `--json` to emit machine-readable JSON only on stdout.
-
-### Examples
-
-```bash
-hpl capabilities --json
-hpl health --json
-hpl notes list --json
-hpl notes get the-invitation --json
-```
+<!--
+  HPL CLI
+  The Human Pattern Lab
+
+  This README is written for humans.
+  Design rationale lives in DESIGN.md.
+-->
+
+# HPL CLI (Alpha) 🧭🦊
+
+![AI-Forward CLI](https://img.shields.io/badge/AI--Forward%20CLI-black?style=flat-square)
+![automation-safe by design](https://img.shields.io/badge/automation--safe%20by%20design-8b5cf6?style=flat-square)
+![npm (alpha)](https://img.shields.io/npm/v/@thehumanpatternlab/hpl/alpha?label=alpha&color=8b5cf6&style=flat-square)
+![Carmel Judgment](https://github.com/AdaInTheLab/the-human-pattern-lab-cli/actions/workflows/carmel-judgment.yml/badge.svg)
+
+> **Status:** Alpha  
+> A modern, automation-safe CLI for The Human Pattern Lab.
+
+**HPL** is the official command-line interface for **The Human Pattern Lab**.
+
+Formerly developed under the codename **Skulk**, HPL is built to work just as well for humans at the keyboard as it does for automation, CI, and agent-driven workflows.
+
+This package is in **active alpha development**. Interfaces are stabilizing, but iteration is expected.
+
+---
+
+## What HPL Connects To
+
+HPL is a deterministic bridge between:
+
+- the **Human Pattern Lab Content Repository** (source of truth)
+- the **Human Pattern Lab API** (runtime index and operations)
+
+Written content lives as Markdown in a dedicated content repository.  
+The API syncs and indexes that content so it can be rendered by user interfaces.
+
+By default, HPL 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.
+
+---
+
+## Authentication
+
+HPL supports token-based authentication via the `HPL_TOKEN` environment variable.
+
+```bash
+export HPL_TOKEN="your-api-token"
+```
+
+(Optional) Override the API endpoint:
+
+```bash
+export HPL_BASE_URL="https://api.thehumanpatternlab.com"
+```
+
+> `HPL_BASE_URL` should point to the **root** of a Human Pattern Lab API deployment.  
+> Do not include additional path segments.
+
+Some API endpoints may require authentication depending on server configuration.
+
+---
+
+## Quick Start
+
+### Install (alpha)
+
+```bash
+npm install -g @thehumanpatternlab/hpl@alpha
+```
+
+### Sync Lab Notes from the content repository
+
+```bash
+hpl notes sync --content-repo AdaInTheLab/the-human-pattern-lab-content
+```
+
+This pulls structured Markdown content from the repository and synchronizes it into the Human Pattern Lab system.
+
+### Machine-readable output
+
+```bash
+hpl --json notes sync
+```
+
+---
+
+## Content Source Configuration (Optional)
+
+By default, `notes sync` expects a content repository with the following structure:
+
+```text
+labnotes/
+  en/
+    *.md
+  ko/
+    *.md
+```
+
+You may pin a default content repository using an environment variable:
+
+```bash
+export HPL_CONTENT_REPO="AdaInTheLab/the-human-pattern-lab-content"
+```
+
+This allows `hpl notes sync` to run without explicitly passing `--content-repo`.
+
+---
+
+## Commands
+
+```text
+hpl <domain> <action> [options]
+```
+
+### notes
+
+**Read operations:**
+- `hpl notes list` - List all published Lab Notes
+- `hpl notes get <slug>` - Get a specific Lab Note by slug
+
+**Write operations:** (requires `HPL_TOKEN`)
+- `hpl notes create --title "..." --slug "..." --file note.md` - Create a new Lab Note
+- `hpl notes update <slug> --title "..." --file note.md` - Update an existing Lab Note
+
+**Bulk operations:**
+- `hpl notes sync --content-repo <owner/name|url>` - Sync from content repository
+- `hpl notes sync --dir <path>` - Sync from local directory (advanced / local development)
+
+See [WRITE_OPERATIONS_GUIDE.md](./WRITE_OPERATIONS_GUIDE.md) for detailed write operations documentation.
+
+### health
+
+```bash
+hpl health
+```
+
+### version
+
+```bash
+hpl version
+```
+
+---
+
+## JSON Output Contract
+
+Structured output is treated as a **contract**, not a courtesy.
+
+When `--json` is provided:
+
+- stdout contains **only valid JSON**
+- stderr is used for logs and diagnostics
+- exit codes are deterministic
+
+A verification step is included:
+
+```bash
+npm run json:check
+```
+
+This command fails if any non-JSON output appears on stdout.
+
+---
+
+## What HPL Is Not
+
+HPL is not:
+- a chatbot interface
+- an agent framework
+- a memory system
+- an inference layer
+
+It is a command-line tool for interacting with Human Pattern Lab systems in a predictable, human-owned way.
+
+---
+
+**The Human Pattern Lab**  
+https://thehumanpatternlab.com
+
+*The lantern is lit.  
+The foxes are watching.*

package/dist/bin/hpl.js

@@ -2,157 +2,32 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — CLI ENTRYPOINT
    -----------------------------------------------------------
-   Commands:
-     - version
-     - capabilities
-     - health
-     - notes list
-     - notes get <slug>
-   Contract: --json => JSON only on stdout
+   Purpose:
+     - Register top-level commands
+     - Define global flags (--json)
+     - Parse argv
+   Contract:
+     --json => JSON only on stdout (enforced in command handlers)
    Notes:
-     - Avoid process.exit() inside command handlers (can trip libuv on Windows + tsx).
+     Avoid process.exit() inside handlers (Windows + tsx stability).
    =========================================================== */
 import { Command } from "commander";
-import { writeHuman, writeJson } from "../src/io";
-import { EXIT } from "../src/contract/exitCodes";
-import { runVersion } from "../src/commands/version";
-import { runCapabilities } from "../src/commands/capabilities";
-import { runHealth } from "../src/commands/health";
-import { runNotesList } from "../src/commands/notes/list";
-import { runNotesGet } from "../src/commands/notes/get";
-import { renderTable } from "../src/render/table";
-import { formatTags, safeLine, stripHtml } from "../src/render/text";
+import { versionCommand } from "../src/commands/version.js";
+import { capabilitiesCommand } from "../src/commands/capabilities.js";
+import { healthCommand } from "../src/commands/health.js";
+import { notesCommand } from "../src/commands/notes/notes.js";
+import { EXIT } from "../src/contract/exitCodes.js";
 const program = new Command();
 program
     .name("hpl")
     .description("Human Pattern Lab CLI (alpha)")
     .option("--json", "Emit contract JSON only on stdout")
-    .showHelpAfterError();
-function setExit(code) {
-    // Let Node exit naturally (important for Windows + tsx stability).
-    process.exitCode = code;
-}
-program
-    .command("version")
-    .description("Show CLI version (contract: show_version)")
-    .action(() => {
-    const opts = program.opts();
-    const envelope = runVersion("version");
-    if (opts.json)
-        writeJson(envelope);
-    else
-        writeHuman(`${envelope.data.name} ${envelope.data.version}`);
-    setExit(EXIT.OK);
-});
-program
-    .command("capabilities")
-    .description("Show CLI capabilities for agents (contract: show_capabilities)")
-    .action(() => {
-    const opts = program.opts();
-    const envelope = runCapabilities("capabilities");
-    if (opts.json)
-        writeJson(envelope);
-    else {
-        writeHuman(`intentTier: ${envelope.data.intentTier}`);
-        writeHuman(`schemaVersions: ${envelope.data.schemaVersions.join(", ")}`);
-        writeHuman(`supportedIntents:`);
-        for (const i of envelope.data.supportedIntents)
-            writeHuman(`  - ${i}`);
-    }
-    setExit(EXIT.OK);
-});
-program
-    .command("health")
-    .description("Check API health (contract: check_health)")
-    .action(async () => {
-    const opts = program.opts();
-    const result = await runHealth("health");
-    if (opts.json) {
-        writeJson(result.envelope);
-    }
-    else {
-        if (result.envelope.status === "ok") {
-            const d = result.envelope.data;
-            const db = d.dbPath ? ` (db: ${d.dbPath})` : "";
-            writeHuman(`ok${db}`);
-        }
-        else {
-            const e = result.envelope.error;
-            writeHuman(`error: ${e.code} — ${e.message}`);
-        }
-    }
-    setExit(result.exitCode);
-});
-const notes = program.command("notes").description("Lab Notes commands");
-notes
-    .command("list")
-    .description("List lab notes (contract: render_lab_note)")
-    .option("--limit <n>", "Limit number of rows (client-side)", (v) => parseInt(v, 10))
-    .action(async (cmdOpts) => {
-    const opts = program.opts();
-    const result = await runNotesList("notes list");
-    if (opts.json) {
-        writeJson(result.envelope);
-        setExit(result.exitCode);
-        return;
-    }
-    if (result.envelope.status !== "ok") {
-        const e = result.envelope.error;
-        writeHuman(`error: ${e.code} — ${e.message}`);
-        setExit(result.exitCode);
-        return;
-    }
-    const data = result.envelope.data;
-    const rows = data.notes ?? [];
-    const limit = Number.isFinite(cmdOpts.limit) && cmdOpts.limit > 0 ? cmdOpts.limit : rows.length;
-    const slice = rows.slice(0, limit);
-    const table = renderTable(slice, [
-        { header: "slug", width: 28, value: (n) => safeLine(String(n.slug ?? "")) },
-        { header: "title", width: 34, value: (n) => safeLine(String(n.title ?? "")) },
-        { header: "status", width: 10, value: (n) => safeLine(String(n.status ?? "-")) },
-        { header: "dept", width: 8, value: (n) => safeLine(String(n.department_id ?? "-")) },
-        { header: "tags", width: 22, value: (n) => formatTags(n.tags) },
-    ]);
-    writeHuman(table);
-    writeHuman(`\ncount: ${data.count}`);
-    setExit(result.exitCode);
-});
-notes
-    .command("get")
-    .description("Get a lab note by slug (contract: render_lab_note)")
-    .argument("<slug>", "Lab Note slug")
-    .option("--raw", "Print raw contentHtml (no HTML stripping)")
-    .action(async (slug, cmdOpts) => {
-    const opts = program.opts();
-    const result = await runNotesGet(slug, "notes get");
-    if (opts.json) {
-        writeJson(result.envelope);
-        setExit(result.exitCode);
-        return;
-    }
-    if (result.envelope.status !== "ok") {
-        const e = result.envelope.error;
-        writeHuman(`error: ${e.code} — ${e.message}`);
-        setExit(result.exitCode);
-        return;
-    }
-    const n = result.envelope.data;
-    writeHuman(`# ${n.title}`);
-    writeHuman(`slug: ${n.slug}`);
-    if (n.status)
-        writeHuman(`status: ${n.status}`);
-    if (n.type)
-        writeHuman(`type: ${n.type}`);
-    if (n.department_id)
-        writeHuman(`department_id: ${n.department_id}`);
-    if (n.published)
-        writeHuman(`published: ${n.published}`);
-    if (Array.isArray(n.tags))
-        writeHuman(`tags: ${formatTags(n.tags)}`);
-    writeHuman("");
-    const body = cmdOpts.raw ? String(n.contentHtml ?? "") : stripHtml(String(n.contentHtml ?? ""));
-    writeHuman(body || "(no content)");
-    setExit(result.exitCode);
+    .showHelpAfterError()
+    .configureHelp({ helpWidth: 100 });
+program.addCommand(versionCommand());
+program.addCommand(capabilitiesCommand());
+program.addCommand(healthCommand());
+program.addCommand(notesCommand());
+program.parseAsync(process.argv).catch(() => {
+    process.exitCode = EXIT.UNKNOWN;
 });
-// Let commander handle errors; set exit code without hard exit.
-program.parseAsync(process.argv).catch(() => setExit(EXIT.UNKNOWN));

package/dist/src/commands/capabilities.js

@@ -1,9 +1,33 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: capabilities
    =========================================================== */
+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";
+export function capabilitiesCommand() {
+    return new Command("capabilities")
+        .description("Show CLI capabilities for agents (contract: show_capabilities)")
+        .action((...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const envelope = runCapabilities("capabilities");
+        if (rootOpts.json) {
+            writeJson(envelope);
+        }
+        else {
+            const d = envelope.data ?? {};
+            writeHuman(`intentTier: ${d.intentTier ?? "-"}`);
+            writeHuman(`schemaVersions: ${(d.schemaVersions ?? []).join(", ")}`);
+            writeHuman(`supportedIntents:`);
+            for (const i of d.supportedIntents ?? [])
+                writeHuman(`  - ${i}`);
+        }
+        process.exitCode = EXIT.OK;
+    });
+}
 export function runCapabilities(commandName = "capabilities") {
     const intent = getAlphaIntent("show_capabilities");
     return ok(commandName, intent, getCapabilitiesAlpha());

package/dist/src/commands/health.js

@@ -1,6 +1,8 @@
 /* ===========================================================
    🌌 HUMAN PATTERN LAB — COMMAND: health
    =========================================================== */
+import { Command } from "commander";
+import { writeHuman, writeJson } from "../io.js";
 import { z } from "zod";
 import { getAlphaIntent } from "../contract/intents";
 import { ok, err } from "../contract/envelope";
@@ -10,6 +12,30 @@ const HealthSchema = z.object({
     status: z.string(),
     dbPath: z.string().optional(),
 });
+export function healthCommand() {
+    return new Command("health")
+        .description("Check API health (contract: check_health)")
+        .action(async (...args) => {
+        const cmd = args[args.length - 1];
+        const rootOpts = (cmd.parent?.opts?.() ?? {});
+        const result = await runHealth("health");
+        if (rootOpts.json) {
+            writeJson(result.envelope);
+        }
+        else {
+            if (result.envelope.status === "ok") {
+                const d = result.envelope.data ?? {};
+                const db = d.dbPath ? ` (db: ${d.dbPath})` : "";
+                writeHuman(`ok${db}`);
+            }
+            else {
+                const e = result.envelope.error ?? {};
+                writeHuman(`error: ${e.code ?? "E_UNKNOWN"} — ${e.message ?? "unknown"}`);
+            }
+        }
+        process.exitCode = result.exitCode ?? EXIT.UNKNOWN;
+    });
+}
 export async function runHealth(commandName = "health") {
     const intent = getAlphaIntent("check_health");
     try {

package/dist/src/commands/notes/create.js

@@ -0,0 +1,183 @@
+/* ===========================================================
+   🦊 THE HUMAN PATTERN LAB — HPL CLI
+   -----------------------------------------------------------
+   File: create.ts
+   Role: Notes subcommand: `hpl notes create`
+   Author: Ada (The Human Pattern Lab)
+   Assistant: Claude
+   Lab Unit: SCMS — Systems & Code Management Suite
+   Status: Active
+   -----------------------------------------------------------
+   Purpose:
+     Create a new Lab Note via API using the upsert endpoint.
+     Supports both markdown file input and inline content.
+   -----------------------------------------------------------
+   Design:
+     - Core function returns { envelope, exitCode }
+     - Commander adapter decides json vs human rendering
+     - Requires authentication via HPL_TOKEN
+   =========================================================== */
+import fs from "node:fs";
+import { Command } from "commander";
+import { getOutputMode, printJson } from "../../cli/output.js";
+import { renderText } from "../../render/text.js";
+import { LabNoteUpsertSchema } from "../../types/labNotes.js";
+import { HPL_TOKEN } from "../../lib/config.js";
+import { getAlphaIntent } from "../../contract/intents.js";
+import { ok, err } from "../../contract/envelope.js";
+import { EXIT } from "../../contract/exitCodes.js";
+import { postJson, HttpError } from "../../http/client.js";
+/**
+ * Core: create a new Lab Note.
+ * Returns structured envelope + exitCode (no printing here).
+ */
+export async function runNotesCreate(options, commandName = "notes.create") {
+    const intent = getAlphaIntent("create_lab_note");
+    // Authentication check
+    const token = HPL_TOKEN();
+    if (!token) {
+        return {
+            envelope: err(commandName, intent, {
+                code: "E_AUTH",
+                message: "Authentication required. Set HPL_TOKEN environment variable or configure token in ~/.humanpatternlab/hpl.json",
+            }),
+            exitCode: EXIT.AUTH,
+        };
+    }
+    // Get markdown content
+    let markdown;
+    if (options.file) {
+        if (!fs.existsSync(options.file)) {
+            return {
+                envelope: err(commandName, intent, {
+                    code: "E_NOT_FOUND",
+                    message: `File not found: ${options.file}`,
+                }),
+                exitCode: EXIT.NOT_FOUND,
+            };
+        }
+        try {
+            markdown = fs.readFileSync(options.file, "utf-8");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                envelope: err(commandName, intent, {
+                    code: "E_IO",
+                    message: `Failed to read file: ${msg}`,
+                }),
+                exitCode: EXIT.IO,
+            };
+        }
+    }
+    else if (options.markdown) {
+        markdown = options.markdown;
+    }
+    else {
+        return {
+            envelope: err(commandName, intent, {
+                code: "E_VALIDATION",
+                message: "Either --markdown or --file is required",
+            }),
+            exitCode: EXIT.VALIDATION,
+        };
+    }
+    // Build payload
+    const payload = {
+        slug: options.slug,
+        title: options.title,
+        markdown,
+        locale: options.locale,
+        subtitle: options.subtitle,
+        summary: options.summary,
+        tags: options.tags,
+        published: options.published,
+        status: options.status,
+        type: options.type,
+        dept: options.dept,
+    };
+    // Validate payload
+    const parsed = LabNoteUpsertSchema.safeParse(payload);
+    if (!parsed.success) {
+        return {
+            envelope: err(commandName, intent, {
+                code: "E_VALIDATION",
+                message: "Invalid note data",
+                details: parsed.error.flatten(),
+            }),
+            exitCode: EXIT.VALIDATION,
+        };
+    }
+    // Make API request
+    try {
+        const response = await postJson("/lab-notes/upsert", parsed.data, token);
+        return {
+            envelope: ok(commandName, intent, {
+                slug: response.slug,
+                action: response.action ?? "created",
+                message: `Lab Note ${response.action ?? "created"}: ${response.slug}`,
+            }),
+            exitCode: EXIT.OK,
+        };
+    }
+    catch (e) {
+        if (e instanceof HttpError) {
+            if (e.status === 401 || e.status === 403) {
+                return {
+                    envelope: err(commandName, intent, {
+                        code: "E_AUTH",
+                        message: "Authentication failed. Check your HPL_TOKEN.",
+                    }),
+                    exitCode: EXIT.AUTH,
+                };
+            }
+            const code = e.status && e.status >= 500 ? "E_SERVER" : "E_HTTP";
+            return {
+                envelope: err(commandName, intent, {
+                    code,
+                    message: `API request failed (${e.status ?? "unknown"})`,
+                    details: e.body ? e.body.slice(0, 500) : undefined,
+                }),
+                exitCode: e.status && e.status >= 500 ? EXIT.SERVER : EXIT.NETWORK,
+            };
+        }
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            envelope: err(commandName, intent, {
+                code: "E_UNKNOWN",
+                message: msg,
+            }),
+            exitCode: EXIT.UNKNOWN,
+        };
+    }
+}
+/**
+ * Commander: `hpl notes create`
+ */
+export function notesCreateSubcommand() {
+    return new Command("create")
+        .description("Create a new Lab Note (contract: create_lab_note)")
+        .requiredOption("--title <title>", "Note title")
+        .requiredOption("--slug <slug>", "Note slug (unique identifier)")
+        .option("--markdown <text>", "Markdown content (inline)")
+        .option("--file <path>", "Path to markdown file")
+        .option("--locale <code>", "Locale code (default: en)", "en")
+        .option("--subtitle <text>", "Note subtitle")
+        .option("--summary <text>", "Note summary")
+        .option("--tags <tags>", "Comma-separated tags", (val) => val.split(",").map((t) => t.trim()))
+        .option("--published <date>", "Publication date (ISO format)")
+        .option("--status <status>", "Note status (draft|published|archived)", "draft")
+        .option("--type <type>", "Note type (labnote|paper|memo|lore|weather)", "labnote")
+        .option("--dept <dept>", "Department code")
+        .action(async (opts, cmd) => {
+        const mode = getOutputMode(cmd);
+        const { envelope, exitCode } = await runNotesCreate(opts, "notes.create");
+        if (mode === "json") {
+            printJson(envelope);
+        }
+        else {
+            renderText(envelope);
+        }
+        process.exitCode = exitCode;
+    });
+}