architectonic 0.0.3 → 0.0.4

package/README.md

@@ -12,8 +12,8 @@ skills     -- reusable procedures and capabilities
 ```
 
 The initial placeholder releases were intentionally minimal. Starting in
-`0.0.3`, `architectonic add` becomes real: it clones the selected layer
-repositories into a target directory and records them in `architectonic.json`.
+`0.0.4`, `architectonic add` installs the selected layer repositories from
+either git or npm sources and records them in `architectonic.json`.
 
 ## Command shape
 
@@ -44,9 +44,12 @@ npx architectonic add project
 npx architectonic add skills
 npx architectonic add teleology identity skills
 npx architectonic add skills --dir ./vendor
+npx architectonic add teleology --source npm
+npx architectonic list
+npx architectonic doctor
 ```
 
-`add` clones from the Architectonic GitHub organization into the current
+`add` installs from the Architectonic GitHub organization into the current
 directory by default:
 
 ```text
@@ -62,6 +65,30 @@ directory by default:
 If a target directory already exists, the command stops instead of silently
 overwriting it.
 
+## Sources
+
+`add` supports two source modes:
+
+```text
+--source git   # clone from GitHub or another git base
+--source npm   # pack and extract from npm packages
+```
+
+The default is `git`.
+
+Environment overrides:
+
+```text
+ARCHITECTONIC_SOURCE_BASE   # override the git source base
+ARCHITECTONIC_NPM_BASE      # override the npm package base or local package root
+ARCHITECTONIC_ADD_SOURCE    # change the default source mode
+```
+
+`list` reads `architectonic.json` and shows installed layers.
+
+`doctor` verifies that each recorded layer still exists and that the installed
+package metadata matches the expected layer.
+
 ## Run vs install
 
 ```text

package/bin/architectonic.js

@@ -4,12 +4,19 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-const VERSION = "0.0.3";
+const VERSION = "0.0.4";
 const args = process.argv.slice(2);
 const [command, ...rest] = args;
 const supported = ["teleology", "identity", "project", "skills"];
 const supportedSet = new Set(supported);
 const repoBase = process.env.ARCHITECTONIC_SOURCE_BASE || "https://github.com/architectonic";
+const npmBase = process.env.ARCHITECTONIC_NPM_BASE || "";
+const packageMap = {
+  teleology: "teleology",
+  identity: "architectonic-identity",
+  project: "architectonic-project",
+  skills: "architectonic-skills",
+};
 
 function printHelp() {
   console.log(`architectonic ${VERSION}
@@ -22,6 +29,9 @@ Usage:
   npx architectonic add <teleology|identity|project|skills>
   npx architectonic add teleology identity skills
   npx architectonic add skills --dir ./vendor
+  npx architectonic add teleology --source npm
+  npx architectonic list
+  npx architectonic doctor
 
 Layers:
   teleology  purpose, principles, doctrine, governance
@@ -35,13 +45,14 @@ Run vs install:
   npm install -g architectonic install globally
 
 What add does:
-  Clones the selected layer repositories into the target directory
-  and records them in architectonic.json.`);
+  Installs the selected layer repositories into the target directory
+  from git or npm sources and records them in architectonic.json.`);
 }
 
 function parseAddArgs(tokens) {
   const targets = [];
   let installDir = process.cwd();
+  let source = process.env.ARCHITECTONIC_ADD_SOURCE || "git";
 
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index];
@@ -62,13 +73,26 @@ function parseAddArgs(tokens) {
       installDir = path.resolve(token.slice("--out=".length));
       continue;
     }
+    if (token === "--source") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error("Missing value for --source");
+      }
+      source = next;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--source=")) {
+      source = token.slice("--source=".length);
+      continue;
+    }
     if (token.startsWith("-")) {
       throw new Error(`Unknown option: ${token}`);
     }
     targets.push(token);
   }
 
-  return { targets, installDir };
+  return { targets, installDir, source };
 }
 
 function ensureGitAvailable() {
@@ -78,6 +102,20 @@ function ensureGitAvailable() {
   }
 }
 
+function ensureNpmAvailable() {
+  const result = spawnSync("npm", ["--version"], { encoding: "utf8", shell: true });
+  if (result.status !== 0) {
+    throw new Error("npm is required on PATH for `architectonic add --source npm`.");
+  }
+}
+
+function ensureTarAvailable() {
+  const result = spawnSync("tar", ["--version"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error("tar is required on PATH for npm package extraction.");
+  }
+}
+
 function repoUrlFor(target) {
   const normalizedBase = repoBase.replace(/\\/g, "/");
   if (/^(?:[A-Za-z]:\/|\/|\.{1,2}\/)/.test(normalizedBase)) {
@@ -86,10 +124,31 @@ function repoUrlFor(target) {
   return `${normalizedBase}/${target}.git`;
 }
 
+function packageSpecFor(target) {
+  const packageName = packageMap[target];
+  if (!packageName) {
+    throw new Error(`No npm package mapping defined for ${target}`);
+  }
+  if (!npmBase) {
+    return packageName;
+  }
+  const normalizedBase = npmBase.replace(/\\/g, "/");
+  if (/^(?:[A-Za-z]:\/|\/|\.{1,2}\/)/.test(normalizedBase)) {
+    return path.resolve(normalizedBase, target);
+  }
+  return normalizedBase.endsWith("/")
+    ? `${normalizedBase}${packageName}`
+    : `${normalizedBase}/${packageName}`;
+}
+
 function targetPathFor(installDir, target) {
   return path.join(installDir, target);
 }
 
+function manifestPathFor(installDir) {
+  return path.join(installDir, "architectonic.json");
+}
+
 function readManifest(manifestPath) {
   if (!fs.existsSync(manifestPath)) {
     return {
@@ -129,11 +188,105 @@ function cloneLayer(target, installDir) {
     name: target,
     repo: repoUrl,
     path: targetPath,
+    source: "git",
   };
 }
 
+function packNpmLayer(target, installDir) {
+  const packageSpec = packageSpecFor(target);
+  const targetPath = targetPathFor(installDir, target);
+  const tempRoot = fs.mkdtempSync(path.join(installDir, "architectonic-npm-"));
+  const pack = spawnSync("npm", ["pack", packageSpec, "--pack-destination", tempRoot], {
+    cwd: installDir,
+    encoding: "utf8",
+    stdio: "pipe",
+    shell: true,
+  });
+
+  if (pack.status !== 0) {
+    const detail = (pack.stderr || pack.stdout || "").trim();
+    throw new Error(`Failed to pack ${packageSpec}${detail ? `\n${detail}` : ""}`);
+  }
+
+  const tgzName = (pack.stdout || "").trim().split(/\r?\n/).filter(Boolean).pop();
+  if (!tgzName) {
+    throw new Error(`npm pack did not return a tarball name for ${packageSpec}`);
+  }
+
+  const tgzPath = path.join(tempRoot, tgzName);
+  if (!fs.existsSync(tgzPath)) {
+    throw new Error(`Packed tarball not found: ${tgzPath}`);
+  }
+
+  if (fs.existsSync(targetPath)) {
+    throw new Error(`Target already exists: ${targetPath}`);
+  }
+
+  fs.mkdirSync(targetPath, { recursive: true });
+  const extract = spawnSync("tar", ["-xzf", tgzPath, "-C", targetPath], {
+    cwd: installDir,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+
+  if (extract.status !== 0) {
+    const detail = (extract.stderr || extract.stdout || "").trim();
+    throw new Error(`Failed to extract ${tgzPath}${detail ? `\n${detail}` : ""}`);
+  }
+
+  const extractedPackageDir = path.join(targetPath, "package");
+  if (!fs.existsSync(extractedPackageDir)) {
+    throw new Error(`Expected extracted package directory at ${extractedPackageDir}`);
+  }
+
+  for (const entry of fs.readdirSync(extractedPackageDir, { withFileTypes: true })) {
+    const from = path.join(extractedPackageDir, entry.name);
+    const to = path.join(targetPath, entry.name);
+    fs.renameSync(from, to);
+  }
+  fs.rmdirSync(extractedPackageDir);
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+
+  return {
+    name: target,
+    repo: packageSpec,
+    path: targetPath,
+    source: "npm",
+  };
+}
+
+function readInstalledPackageName(layerPath) {
+  const packageJsonPath = path.join(layerPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8")).name || null;
+  } catch {
+    return null;
+  }
+}
+
+function installLayer(target, installDir, source) {
+  if (source === "git") {
+    return cloneLayer(target, installDir);
+  }
+  if (source === "npm") {
+    return packNpmLayer(target, installDir);
+  }
+  throw new Error(`Unsupported source: ${source}. Use git or npm.`);
+}
+
+function loadManifestFromDir(installDir) {
+  const manifestPath = manifestPathFor(installDir);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No architectonic.json found in ${installDir}`);
+  }
+  return { manifestPath, manifest: readManifest(manifestPath) };
+}
+
 function addCommand(tokens) {
-  const { targets, installDir } = parseAddArgs(tokens);
+  const { targets, installDir, source } = parseAddArgs(tokens);
 
   if (!targets.length) {
     throw new Error("Specify one or more layers: teleology, identity, project, skills");
@@ -144,25 +297,37 @@ function addCommand(tokens) {
     throw new Error(`Unknown layer(s): ${invalid.join(", ")}\nSupported layers: ${supported.join(", ")}`);
   }
 
-  ensureGitAvailable();
+  if (source === "git") {
+    ensureGitAvailable();
+  } else if (source === "npm") {
+    ensureNpmAvailable();
+    ensureTarAvailable();
+  } else {
+    throw new Error(`Unsupported source: ${source}. Use git or npm.`);
+  }
+
   fs.mkdirSync(installDir, { recursive: true });
 
   const installed = [];
   for (const target of targets) {
-    console.log(`Adding ${target}...`);
-    installed.push(cloneLayer(target, installDir));
+    console.log(`Adding ${target} from ${source}...`);
+    installed.push(installLayer(target, installDir, source));
   }
 
-  const manifestPath = path.join(installDir, "architectonic.json");
+  const manifestPath = manifestPathFor(installDir);
   const manifest = readManifest(manifestPath);
   manifest.installed_at = new Date().toISOString();
-  manifest.source_base = repoBase;
+  manifest.last_source = source;
+  manifest.git_source_base = repoBase;
+  manifest.npm_source_base = npmBase || "registry";
 
   for (const item of installed) {
     manifest.layers[item.name] = {
-      repo: item.repo,
+      source: item.source,
+      ref: item.repo,
       path: `./${path.relative(installDir, item.path).replace(/\\/g, "/")}`,
       installed_at: manifest.installed_at,
+      package_name: readInstalledPackageName(item.path),
     };
   }
 
@@ -173,6 +338,77 @@ function addCommand(tokens) {
   console.log(`Wrote ${manifestPath}`);
 }
 
+function listCommand(tokens) {
+  const installDir = tokens[0] ? path.resolve(tokens[0]) : process.cwd();
+  const { manifest } = loadManifestFromDir(installDir);
+  const entries = Object.entries(manifest.layers || {});
+
+  if (!entries.length) {
+    console.log("No layers installed.");
+    return;
+  }
+
+  for (const [name, layer] of entries) {
+    console.log(`${name}`);
+    console.log(`  source: ${layer.source || "unknown"}`);
+    console.log(`  path:   ${layer.path || "unknown"}`);
+    console.log(`  ref:    ${layer.ref || "unknown"}`);
+    if (layer.package_name) {
+      console.log(`  pkg:    ${layer.package_name}`);
+    }
+  }
+}
+
+function doctorCommand(tokens) {
+  const installDir = tokens[0] ? path.resolve(tokens[0]) : process.cwd();
+  const { manifestPath, manifest } = loadManifestFromDir(installDir);
+  const entries = Object.entries(manifest.layers || {});
+  let failures = 0;
+
+  console.log(`architectonic doctor`);
+  console.log(`  root: ${installDir}`);
+  console.log(`  manifest: ${manifestPath}`);
+
+  if (!entries.length) {
+    console.log(`  [fail] no installed layers recorded`);
+    process.exit(1);
+  }
+
+  for (const [name, layer] of entries) {
+    const relativePath = String(layer.path || "");
+    const layerPath = path.resolve(installDir, relativePath);
+    const packageJsonPath = path.join(layerPath, "package.json");
+    const exists = fs.existsSync(layerPath);
+    const hasPackageJson = fs.existsSync(packageJsonPath);
+    const packageName = hasPackageJson ? readInstalledPackageName(layerPath) : null;
+    const expectedPackageName = packageMap[name];
+
+    if (!exists) {
+      console.log(`  [fail] ${name}: missing directory ${layerPath}`);
+      failures += 1;
+      continue;
+    }
+
+    if (!hasPackageJson) {
+      console.log(`  [fail] ${name}: missing package.json`);
+      failures += 1;
+      continue;
+    }
+
+    if (packageName && expectedPackageName && packageName !== expectedPackageName) {
+      console.log(`  [fail] ${name}: expected package ${expectedPackageName}, found ${packageName}`);
+      failures += 1;
+      continue;
+    }
+
+    console.log(`  [ok] ${name}: ${relativePath} (${layer.source || "unknown"})`);
+  }
+
+  if (failures > 0) {
+    process.exit(1);
+  }
+}
+
 try {
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -184,6 +420,16 @@ try {
     process.exit(0);
   }
 
+  if (command === "list") {
+    listCommand(rest);
+    process.exit(0);
+  }
+
+  if (command === "doctor") {
+    doctorCommand(rest);
+    process.exit(0);
+  }
+
   throw new Error(`Unknown command: ${command}\nRun \`architectonic help\` for usage.`);
 } catch (error) {
   console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architectonic",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "CLI for composing agentic system layers such as teleology, identity, project, and skills.",
   "license": "Apache-2.0",
   "type": "module",