architectonic 0.0.1 → 0.0.3

package/README.md

@@ -1,41 +1,71 @@
 # architectonic
 
-`architectonic` is a command-line tool for installing and wiring the core layers of an agentic system.
+`architectonic` is a command-line tool for composing the core layers of an agentic system.
 
 Those layers currently include:
 
 ```text
-teleology  -- purpose, truth, evidence, governance
-identity   -- actors, roles, authority, privacy, constraints
-project    -- source-grounded project operating context
-skills     -- reusable procedures
+teleology  -- purpose, principles, doctrine, governance
+identity   -- actors, roles, authority, boundaries
+project    -- operating context for a concrete initiative
+skills     -- reusable procedures and capabilities
 ```
 
-The initial `0.0.1` release is intentionally minimal. Its job is to reserve the
-package name and establish the top-level command surface for future install,
-cascade, and upkeep workflows.
+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`.
 
-## Planned direction
+## Command shape
 
-Future versions may support commands such as:
+The primary interaction model is:
 
 ```text
 architectonic add teleology
 architectonic add identity
 architectonic add project
 architectonic add skills
+architectonic add teleology identity skills
 architectonic doctor
+architectonic list
 architectonic update
 ```
 
+`add` is explicit and leaves room for future verbs such as `doctor`, `list`,
+`update`, and `remove`.
+
 ## Current behavior
 
-For now, the CLI only exposes:
+The primary implemented command is:
+
+```text
+npx architectonic add teleology
+npx architectonic add identity
+npx architectonic add project
+npx architectonic add skills
+npx architectonic add teleology identity skills
+npx architectonic add skills --dir ./vendor
+```
+
+`add` clones from the Architectonic GitHub organization into the current
+directory by default:
 
 ```text
-npx architectonic
-npx architectonic help
+./teleology
+./identity
+./project
+./skills
+./architectonic.json
 ```
 
-The `add` surface is reserved, but the installer logic is not implemented in
-`0.0.1` yet.
+`architectonic.json` records what was installed and where it landed.
+
+If a target directory already exists, the command stops instead of silently
+overwriting it.
+
+## Run vs install
+
+```text
+npx architectonic ...        # run immediately
+npm install architectonic    # install as a dependency
+npm install -g architectonic # install globally, then run `architectonic ...`
+```

package/bin/architectonic.js

@@ -1,42 +1,191 @@
 #!/usr/bin/env node
 
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const VERSION = "0.0.3";
 const args = process.argv.slice(2);
-const [command, target] = args;
+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";
 
 function printHelp() {
-  console.log(`architectonic 0.0.1
+  console.log(`architectonic ${VERSION}
 
-CLI for installing and wiring the core layers of an agentic system.
+CLI for composing the core layers of an agentic system.
 
 Usage:
   npx architectonic
   npx architectonic help
   npx architectonic add <teleology|identity|project|skills>
+  npx architectonic add teleology identity skills
+  npx architectonic add skills --dir ./vendor
+
+Layers:
+  teleology  purpose, principles, doctrine, governance
+  identity   actors, roles, authority, boundaries
+  project    operating context for a concrete initiative
+  skills     reusable procedures and capabilities
+
+Run vs install:
+  npx architectonic ...        run immediately
+  npm install architectonic    install in a project
+  npm install -g architectonic install globally
+
+What add does:
+  Clones the selected layer repositories into the target directory
+  and records them in architectonic.json.`);
+}
+
+function parseAddArgs(tokens) {
+  const targets = [];
+  let installDir = process.cwd();
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--dir" || token === "--out") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      installDir = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      installDir = path.resolve(token.slice("--dir=".length));
+      continue;
+    }
+    if (token.startsWith("--out=")) {
+      installDir = path.resolve(token.slice("--out=".length));
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    targets.push(token);
+  }
+
+  return { targets, installDir };
+}
+
+function ensureGitAvailable() {
+  const result = spawnSync("git", ["--version"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error("git is required on PATH for `architectonic add`.");
+  }
+}
 
-Status:
-  0.0.1 reserves the public CLI name and establishes the command surface.
-  The add subcommands are placeholders in this initial release.`);
+function repoUrlFor(target) {
+  const normalizedBase = repoBase.replace(/\\/g, "/");
+  if (/^(?:[A-Za-z]:\/|\/|\.{1,2}\/)/.test(normalizedBase)) {
+    return path.resolve(normalizedBase, target);
+  }
+  return `${normalizedBase}/${target}.git`;
 }
 
-if (!command || command === "help" || command === "--help" || command === "-h") {
-  printHelp();
-  process.exit(0);
+function targetPathFor(installDir, target) {
+  return path.join(installDir, target);
 }
 
-if (command === "add") {
-  const supported = new Set(["teleology", "identity", "project", "skills"]);
-  if (!target || !supported.has(target)) {
-    console.error("Specify one of: teleology, identity, project, skills");
-    process.exit(1);
+function readManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath)) {
+    return {
+      schema_version: 1,
+      installed_at: new Date().toISOString(),
+      layers: {},
+    };
   }
 
-  console.log(`architectonic add ${target}`);
+  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+}
+
+function writeManifest(manifestPath, manifest) {
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+function cloneLayer(target, installDir) {
+  const repoUrl = repoUrlFor(target);
+  const targetPath = targetPathFor(installDir, target);
+
+  if (fs.existsSync(targetPath)) {
+    throw new Error(`Target already exists: ${targetPath}`);
+  }
+
+  const clone = spawnSync("git", ["clone", repoUrl, targetPath], {
+    cwd: installDir,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+
+  if (clone.status !== 0) {
+    const detail = (clone.stderr || clone.stdout || "").trim();
+    throw new Error(`Failed to clone ${repoUrl}${detail ? `\n${detail}` : ""}`);
+  }
+
+  return {
+    name: target,
+    repo: repoUrl,
+    path: targetPath,
+  };
+}
+
+function addCommand(tokens) {
+  const { targets, installDir } = parseAddArgs(tokens);
+
+  if (!targets.length) {
+    throw new Error("Specify one or more layers: teleology, identity, project, skills");
+  }
+
+  const invalid = targets.filter((target) => !supportedSet.has(target));
+  if (invalid.length) {
+    throw new Error(`Unknown layer(s): ${invalid.join(", ")}\nSupported layers: ${supported.join(", ")}`);
+  }
+
+  ensureGitAvailable();
+  fs.mkdirSync(installDir, { recursive: true });
+
+  const installed = [];
+  for (const target of targets) {
+    console.log(`Adding ${target}...`);
+    installed.push(cloneLayer(target, installDir));
+  }
+
+  const manifestPath = path.join(installDir, "architectonic.json");
+  const manifest = readManifest(manifestPath);
+  manifest.installed_at = new Date().toISOString();
+  manifest.source_base = repoBase;
+
+  for (const item of installed) {
+    manifest.layers[item.name] = {
+      repo: item.repo,
+      path: `./${path.relative(installDir, item.path).replace(/\\/g, "/")}`,
+      installed_at: manifest.installed_at,
+    };
+  }
+
+  writeManifest(manifestPath, manifest);
+
   console.log("");
-  console.log("This placeholder release does not install packages yet.");
-  console.log("It reserves the command contract for future cascade/install behavior.");
-  process.exit(0);
+  console.log(`Installed ${installed.map((item) => item.name).join(", ")} into ${installDir}`);
+  console.log(`Wrote ${manifestPath}`);
 }
 
-console.error(`Unknown command: ${command}`);
-console.error("Run `architectonic help` for usage.");
-process.exit(1);
+try {
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === "add") {
+    addCommand(rest);
+    process.exit(0);
+  }
+
+  throw new Error(`Unknown command: ${command}\nRun \`architectonic help\` for usage.`);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/package.json

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