🐛 fix: Resolve ES module import issues and add style guide

Fix critical ES module import errors and establish comprehensive
style guide to prevent future issues.

Import Fixes:
- Add .js extension to schema import in capabilities.ts
- Fix package.json path from ../../ to ../../../ (for compiled code)
- TypeScript doesn't auto-add extensions for ES Modules

Style Guide:
- Add STYLE_GUIDE.md with complete development conventions
- Add QUICK_REFERENCE.md as one-page cheat sheet
- Cover import rules, commit format, common gotchas
- Include VS Code settings for auto-adding .js extensions

Testing:
- CLI builds successfully (npm run build)
- Global install works (npm install -g .)
- All commands functional (hpl version, capabilities, health)

These guides will help future contributors (biological and digital)
avoid common ES module pitfalls and maintain consistency.

Co-authored-by: Sage <sage@thehumanpatternlab.com>

Author: AdaInTheLab

bin/hpl.ts

@@ -25,7 +25,7 @@ const program = new Command();
 
 program
     .name("hpl")
-    .description("Human Pattern Lab CLI (alpha)")
+    .description("Human Pattern Lab CLI")
     .option("--json", "Emit contract JSON only on stdout")
     .showHelpAfterError()
     .configureHelp({ helpWidth: 100 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehumanpatternlab/hpl",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "description": "AI-forward, automation-safe SDK and CLI for the Human Pattern Lab",
   "type": "module",
   "license": "MIT",

src/__tests__/json-output.test.ts

@@ -13,6 +13,13 @@ describe("CLI --json output contract", () => {
             }
         );
 
+        // Debug output
+        if (result.exitCode !== 0) {
+            console.log("Exit code:", result.exitCode);
+            console.log("stdout:", result.stdout);
+            console.log("stderr:", result.stderr);
+        }
+
         // 1. Process must succeed
         expect(result.exitCode).toBe(0);
 

src/commands/capabilities.ts

@@ -5,9 +5,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";
 
 type GlobalOpts = { json?: boolean };
 

src/commands/health.ts

@@ -5,10 +5,10 @@
 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";
-import { EXIT } from "../contract/exitCodes";
-import { getJson, HttpError } from "../http/client";
+import { getAlphaIntent } from "../contract/intents.js";
+import { ok, err } from "../contract/envelope.js";
+import { EXIT } from "../contract/exitCodes.js";
+import { getJson, HttpError } from "../http/client.js";
 
 const HealthSchema = z.object({
   status: z.string(),

src/commands/version.ts

@@ -5,14 +5,25 @@
 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 { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { readFileSync, existsSync } from "fs";
+import { getAlphaIntent } from "../contract/intents.js";
+import { ok } from "../contract/envelope.js";
 
 type GlobalOpts = { json?: boolean }
 
-const require = createRequire(import.meta.url);
-const pkg = require("../../package.json") as { name: string; version: string };
+// Resolve package.json from current file location (works for both tsx and compiled)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Try source location first (tsx), then compiled location
+let pkgPath = join(__dirname, "../../package.json");
+if (!existsSync(pkgPath)) {
+  pkgPath = join(__dirname, "../../../package.json");
+}
+
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { name: string; version: string };
 
 export function versionCommand(): Command {
   return new Command("version")

src/contract/capabilities.ts

@@ -5,8 +5,8 @@
    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 type Capabilities = {
   intentTier: "alpha" | "full";

src/contract/envelope.ts

@@ -5,8 +5,8 @@
    Guarantee: When --json, stdout emits JSON only (no logs).
    =========================================================== */
 
-import type { IntentDescriptor } from "./intents";
-import { CLI_SCHEMA_VERSION, type ErrorPayload } from "./schema";
+import type { IntentDescriptor } from "./intents.js";
+import { CLI_SCHEMA_VERSION, type ErrorPayload } from "./schema.js";
 
 export type CommandStatus = "ok" | "warn" | "error";
 

src/http/client.ts

@@ -6,7 +6,7 @@
      - 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?: number;

src/index.ts

@@ -26,8 +26,8 @@ const program = new Command();
 
 program
     .name("hpl")
-    .description("Human Pattern Lab CLI (alpha)")
-    .version("0.1.0")
+    .description("Human Pattern Lab CLI")
+    .version("1.0.3")
     .option("--json", "Emit contract JSON only on stdout")
     .configureHelp({ helpWidth: 100 });