opencode-architect 0.3.0 → 0.4.0

package/cli.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { Installer, type Scope } from "./installer";
+
+const VERSION = (JSON.parse(await Bun.file(`${import.meta.dirname}/package.json`).text()) as { version: string }).version;
+
+async function main(): Promise<void> {
+  const { positionals, values } = parseArgs({
+    options: {
+      scope: { type: "string", short: "s" },
+      force: { type: "boolean", short: "f", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+  if (values.version) {
+    console.log(`opencode-architect v${VERSION}`);
+    return;
+  }
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    return;
+  }
+
+  const command = positionals[0];
+  const scopeInput = values.scope;
+  if (scopeInput !== undefined && scopeInput !== "local" && scopeInput !== "global") {
+    console.error(`Invalid scope: ${scopeInput}. Must be "local" or "global".`);
+    process.exit(1);
+  }
+  const scope: Scope = scopeInput === "global" ? "global" : "local";
+  const installer = new Installer();
+
+  try {
+    switch (command) {
+      case "install": {
+        const outcome = await installer.install(scope, { force: values.force, projectDir: process.cwd() });
+        if (outcome.action === "noop") {
+          console.log(`Already installed at version ${VERSION}; nothing to do.`);
+        } else {
+          console.log(`${outcome.action === "installed" ? "Installed" : "Upgraded"} (${scope} scope):`);
+          console.log(`  Agents:     ${outcome.agentsDir}`);
+          console.log(`  References: ${outcome.referencesDir}`);
+          console.log(`  Templates:  ${outcome.templatesDir}`);
+        }
+        if (outcome.pluginRemoved) {
+          console.log("  Removed the plugin entry from opencode.json (switched to copy install).");
+        }
+        if (outcome.skipped.length > 0) {
+          console.log("  Skipped locally modified files (re-run with --force to overwrite):");
+          for (const file of outcome.skipped) console.log(`    ${file}`);
+        }
+        break;
+      }
+      case "uninstall": {
+        const outcome = await installer.uninstall(scope, process.cwd());
+        if (outcome.mode === "none") {
+          console.log(`Nothing to uninstall for the ${scope} scope.`);
+          break;
+        }
+        if (outcome.mode === "copy") {
+          console.log(`Uninstalled (${scope} scope):`);
+          for (const file of outcome.removed) console.log(`  Removed: ${file}`);
+        }
+        if (outcome.pluginRemoved) {
+          console.log("  Removed the plugin entry from opencode.json.");
+        }
+        break;
+      }
+      case "status": {
+        const outcome = await installer.status(scope, process.cwd());
+        const version = outcome.version ?? "-";
+        console.log(`${scope} scope: mode=${outcome.mode} version=${version}`);
+        break;
+      }
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+opencode-architect v${VERSION}
+
+Installs the opencode-architect agent suite by copying agents into the scope
+base's agents/, references into opencode-architect/references/, and templates
+into opencode-architect/templates/, rewriting relative reference paths to
+absolute paths at install time. Copy install and plugin install are mutually
+exclusive per scope.
+
+Commands:
+  install     Copy agents, references, and templates into the scope base
+  uninstall   Remove exactly the files a copy install wrote (or the plugin entry)
+  status      Show install mode and version for a scope
+
+Options:
+  -s, --scope <scope>    "local" (project .opencode/) or "global" (~/.config/opencode/); default local
+  -f, --force            install: remove an existing plugin entry and overwrite locally modified files
+  -h, --help             Show this help message
+  -v, --version          Show version
+
+Examples:
+  opencode-architect install
+  opencode-architect install --scope global
+  opencode-architect uninstall
+  opencode-architect status
+`);
+}
+
+main();

package/installer.ts

@@ -0,0 +1,319 @@
+import { createHash } from "node:crypto";
+import { copyFile, exists, mkdir, readdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { AGENT_FILENAMES, RELATIVE_REFERENCE_REGEX } from "./agent-loader";
+
+export type Scope = "local" | "global";
+export type InstallMode = "none" | "copy" | "plugin";
+export type InstallAction = "installed" | "upgraded" | "noop";
+
+export interface ManifestHashEntry {
+  path: string;
+  hash: string;
+}
+
+export interface Manifest {
+  version: string;
+  agentFiles: string[];
+  referencesDir: string;
+  templatesDir: string;
+  hashes: ManifestHashEntry[];
+}
+
+export interface InstallOptions {
+  force: boolean;
+  projectDir: string;
+}
+
+export interface InstallOutcome {
+  action: InstallAction;
+  scope: Scope;
+  agentsDir: string;
+  referencesDir: string;
+  templatesDir: string;
+  manifestPath: string;
+  copied: string[];
+  skipped: string[];
+  overwritten: string[];
+  pluginRemoved: boolean;
+}
+
+export interface UninstallOutcome {
+  scope: Scope;
+  mode: InstallMode;
+  removed: string[];
+  pluginRemoved: boolean;
+}
+
+export interface StatusOutcome {
+  scope: Scope;
+  mode: InstallMode;
+  version: string | null;
+}
+
+const PACKAGE_NAME = "opencode-architect";
+const MANIFEST_NAME = "opencode-architect.json";
+const ASSETS_AGENTS_DIR = path.join(import.meta.dirname, "assets", "agents");
+const ASSETS_REFERENCES_DIR = path.join(import.meta.dirname, "assets", "references");
+const ASSETS_TEMPLATES_DIR = path.join(import.meta.dirname, "assets", "templates");
+
+export class Installer {
+  public async install(scope: Scope, options: InstallOptions): Promise<InstallOutcome> {
+    const base = this.scopeBase(scope, options.projectDir);
+    const configPath = path.join(base, "opencode.json");
+    const manifestPath = path.join(base, MANIFEST_NAME);
+    const agentsDir = path.join(base, "agents");
+    const referencesDir = path.join(base, "opencode-architect", "references");
+    const templatesDir = path.join(base, "opencode-architect", "templates");
+    const version = await this.getPackageVersion();
+
+    let pluginRemoved = false;
+    if (await this.hasPluginEntry(configPath)) {
+      if (!options.force) {
+        throw new Error(
+          `The "${PACKAGE_NAME}" plugin entry in ${configPath} must be removed before a copy install ` +
+            `(copied agents would silently shadow the plugin's agents). Re-run with --force to remove ` +
+            `the entry and switch this scope to copy install.`,
+        );
+      }
+      await this.removePluginEntry(configPath);
+      pluginRemoved = true;
+    }
+
+    const existingManifest = await this.readManifest(manifestPath);
+    if (existingManifest !== null && existingManifest.version === version) {
+      return {
+        action: "noop",
+        scope,
+        agentsDir,
+        referencesDir,
+        templatesDir,
+        manifestPath,
+        copied: [],
+        skipped: [],
+        overwritten: [],
+        pluginRemoved,
+      };
+    }
+
+    const action: InstallAction = existingManifest === null ? "installed" : "upgraded";
+    const copied: string[] = [];
+    const skipped: string[] = [];
+    const overwritten: string[] = [];
+    const hashes: ManifestHashEntry[] = [];
+
+    await mkdir(agentsDir, { recursive: true });
+    await mkdir(referencesDir, { recursive: true });
+    await mkdir(templatesDir, { recursive: true });
+
+    for (const filename of AGENT_FILENAMES) {
+      const relativePath = path.join("agents", filename);
+      const { action: fileAction, priorHash } = await this.disposition(
+        existingManifest,
+        base,
+        relativePath,
+        options.force,
+      );
+      if (fileAction === "skip") {
+        skipped.push(relativePath);
+        hashes.push({ path: relativePath, hash: priorHash as string });
+        continue;
+      }
+      const source = await readFile(path.join(ASSETS_AGENTS_DIR, filename), "utf-8");
+      await writeFile(path.join(base, relativePath), rewriteReferencePaths(source, referencesDir, templatesDir));
+      hashes.push({ path: relativePath, hash: await this.sha256File(path.join(base, relativePath)) });
+      if (fileAction === "overwrite") overwritten.push(relativePath);
+      else copied.push(relativePath);
+    }
+
+    for (const entry of await readdir(ASSETS_REFERENCES_DIR)) {
+      const relativePath = path.join("opencode-architect", "references", entry);
+      const { action: fileAction, priorHash } = await this.disposition(
+        existingManifest,
+        base,
+        relativePath,
+        options.force,
+      );
+      if (fileAction === "skip") {
+        skipped.push(relativePath);
+        hashes.push({ path: relativePath, hash: priorHash as string });
+        continue;
+      }
+      await copyFile(path.join(ASSETS_REFERENCES_DIR, entry), path.join(base, relativePath));
+      hashes.push({ path: relativePath, hash: await this.sha256File(path.join(base, relativePath)) });
+      if (fileAction === "overwrite") overwritten.push(relativePath);
+      else copied.push(relativePath);
+    }
+
+    for (const entry of await readdir(ASSETS_TEMPLATES_DIR)) {
+      const relativePath = path.join("opencode-architect", "templates", entry);
+      const { action: fileAction, priorHash } = await this.disposition(
+        existingManifest,
+        base,
+        relativePath,
+        options.force,
+      );
+      if (fileAction === "skip") {
+        skipped.push(relativePath);
+        hashes.push({ path: relativePath, hash: priorHash as string });
+        continue;
+      }
+      await copyFile(path.join(ASSETS_TEMPLATES_DIR, entry), path.join(base, relativePath));
+      hashes.push({ path: relativePath, hash: await this.sha256File(path.join(base, relativePath)) });
+      if (fileAction === "overwrite") overwritten.push(relativePath);
+      else copied.push(relativePath);
+    }
+
+    const manifest: Manifest = { version, agentFiles: [...AGENT_FILENAMES], referencesDir, templatesDir, hashes };
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+    return { action, scope, agentsDir, referencesDir, templatesDir, manifestPath, copied, skipped, overwritten, pluginRemoved };
+  }
+
+  public async uninstall(scope: Scope, projectDir: string): Promise<UninstallOutcome> {
+    const base = this.scopeBase(scope, projectDir);
+    const configPath = path.join(base, "opencode.json");
+    const manifestPath = path.join(base, MANIFEST_NAME);
+    const manifest = await this.readManifest(manifestPath);
+    const hadPluginEntry = await this.hasPluginEntry(configPath);
+    const removed: string[] = [];
+
+    if (manifest !== null) {
+      for (const entry of manifest.hashes) {
+        const target = path.join(base, entry.path);
+        if (await exists(target)) {
+          await rm(target);
+          removed.push(target);
+        }
+      }
+      await rm(manifestPath);
+      removed.push(manifestPath);
+      await this.removeIfEmpty(path.join(base, "opencode-architect", "templates"));
+      await this.removeIfEmpty(path.join(base, "opencode-architect", "references"));
+      await this.removeIfEmpty(path.join(base, "opencode-architect"));
+      await this.removeIfEmpty(path.join(base, "agents"));
+    }
+
+    let pluginRemoved = false;
+    if (hadPluginEntry) {
+      await this.removePluginEntry(configPath);
+      pluginRemoved = true;
+    }
+
+    const mode: InstallMode = manifest !== null ? "copy" : hadPluginEntry ? "plugin" : "none";
+    return { scope, mode, removed, pluginRemoved };
+  }
+
+  public async status(scope: Scope, projectDir: string): Promise<StatusOutcome> {
+    const base = this.scopeBase(scope, projectDir);
+    const manifest = await this.readManifest(path.join(base, MANIFEST_NAME));
+
+    if (manifest !== null) {
+      return { scope, mode: "copy", version: manifest.version };
+    }
+    if (await this.hasPluginEntry(path.join(base, "opencode.json"))) {
+      return { scope, mode: "plugin", version: null };
+    }
+    return { scope, mode: "none", version: null };
+  }
+
+  private async disposition(
+    manifest: Manifest | null,
+    base: string,
+    relativePath: string,
+    force: boolean,
+  ): Promise<{ action: "copy" | "overwrite" | "skip"; priorHash: string | null }> {
+    if (manifest === null) return { action: "copy", priorHash: null };
+    const priorHash = manifest.hashes.find((entry) => entry.path === relativePath)?.hash ?? null;
+    if (priorHash === null) return { action: "copy", priorHash };
+    const installedPath = path.join(base, relativePath);
+    if (!(await exists(installedPath))) return { action: "copy", priorHash };
+    if ((await this.sha256File(installedPath)) === priorHash) return { action: "copy", priorHash };
+    return { action: force ? "overwrite" : "skip", priorHash };
+  }
+
+  private async sha256File(filePath: string): Promise<string> {
+    return createHash("sha256").update(await readFile(filePath)).digest("hex");
+  }
+
+  private scopeBase(scope: Scope, projectDir: string): string {
+    if (scope === "local") return path.join(projectDir, ".opencode");
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) return path.join(xdgConfigHome, "opencode");
+    return path.join(homedir(), ".config", "opencode");
+  }
+
+  private async readManifest(manifestPath: string): Promise<Manifest | null> {
+    try {
+      return JSON.parse(await readFile(manifestPath, "utf-8")) as Manifest;
+    } catch {
+      return null;
+    }
+  }
+
+  private async hasPluginEntry(configPath: string): Promise<boolean> {
+    const plugins = await this.readPluginArray(configPath);
+    return plugins.some((name) => this.isPluginEntry(name));
+  }
+
+  private async removePluginEntry(configPath: string): Promise<void> {
+    const plugins = await this.readPluginArray(configPath);
+    const remaining = plugins.filter((name) => !this.isPluginEntry(name));
+    const config = await this.readConfig(configPath);
+    if (remaining.length === 0) delete config.plugin;
+    else config.plugin = remaining;
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2) + "\n");
+  }
+
+  private isPluginEntry(name: string): boolean {
+    return name === PACKAGE_NAME || name.startsWith(`${PACKAGE_NAME}@`);
+  }
+
+  private async readPluginArray(configPath: string): Promise<string[]> {
+    const config = await this.readConfig(configPath);
+    const plugins = config.plugin;
+    return Array.isArray(plugins) ? plugins.filter((name): name is string => typeof name === "string") : [];
+  }
+
+  private async readConfig(configPath: string): Promise<Record<string, unknown>> {
+    try {
+      return JSON.parse(await readFile(configPath, "utf-8")) as Record<string, unknown>;
+    } catch {
+      return {};
+    }
+  }
+
+  private async getPackageVersion(): Promise<string> {
+    const content = await readFile(path.join(import.meta.dirname, "package.json"), "utf-8");
+    return (JSON.parse(content) as { version: string }).version;
+  }
+
+  private async removeIfEmpty(directory: string): Promise<void> {
+    if (!(await exists(directory))) return;
+    const contents = await readdir(directory);
+    if (contents.length === 0) await rmdir(directory);
+  }
+}
+
+export function rewriteReferencePaths(content: string, referencesDir: string, templatesDir: string): string {
+  return content.replace(
+    RELATIVE_REFERENCE_REGEX,
+    (token: string, relativePath: string): string => {
+      const normalized = relativePath.replaceAll("\\", "/");
+      const packagedPath = path.resolve(ASSETS_AGENTS_DIR, normalized);
+      const withinReferences = path.relative(ASSETS_REFERENCES_DIR, packagedPath);
+      if (!withinReferences.startsWith("..")) {
+        const installedPath = path.resolve(referencesDir, withinReferences).replaceAll("\\", "/");
+        return `\`${installedPath}\``;
+      }
+      const withinTemplates = path.relative(ASSETS_TEMPLATES_DIR, packagedPath);
+      if (!withinTemplates.startsWith("..")) {
+        const installedPath = path.resolve(templatesDir, withinTemplates).replaceAll("\\", "/");
+        return `\`${installedPath}\``;
+      }
+      return token;
+    },
+  );
+}

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "opencode-architect",
-  "version": "0.3.0",
+  "version": "0.4.0",
+  "description": "OpenCode plugin and CLI with ten specialist agents for agent skills, slash commands, custom tools, plugins, and MCP server integration",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-agents",
+    "agent-skills",
+    "ai-agents",
+    "slash-commands",
+    "mcp",
+    "mcp-server",
+    "coding-agent",
+    "bun"
+  ],
+  "license": "MIT",
   "private": false,
   "type": "module",
   "module": "index.ts",
+  "bin": {
+    "opencode-architect": "cli.ts"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Expert-Vision-Software/opencode-architect.git"
@@ -26,6 +43,8 @@
   "files": [
     "index.ts",
     "agent-loader.ts",
+    "cli.ts",
+    "installer.ts",
     "assets"
   ],
   "dependencies": {

package/assets/templates/package-analysis.template.md

@@ -1,60 +0,0 @@
-# Package Analysis Template
-
-Use this template to document extension analysis before packaging.
-
-## Source Information
-
-- **Source Path**: [path to .opencode/ or existing package]
-- **Source Type**: [project-local | existing-package]
-- **Target Package Name**: opencode-[name]
-
-## Extension Inventory
-
-### Skills
-| Name | Description | Dependencies | Issues |
-| ---- | ----------- | ------------ | ------ |
-|      |             |              |        |
-
-### Commands
-| Name | Description | Template Vars | Issues |
-| ---- | ----------- | ------------- | ------ |
-|      |             |               |        |
-
-### Agents
-| Name | Description | Mode | Issues |
-| ---- | ----------- | ---- | ------ |
-|      |             |      |        |
-
-### Plugins
-| File | Hooks Used | Merge Strategy | Issues |
-| ---- | ---------- | -------------- | ------ |
-|      |            |                |        |
-
-### Tools
-| File | Tool Name | Merge Strategy | Issues |
-| ---- | --------- | -------------- | ------ |
-|      |           |                |        |
-
-## Dependencies
-
-From `.opencode/package.json`:
-- [list dependencies]
-
-## Packaging Assessment
-
-- **Complexity**: [simple | medium | complex]
-- **Requires Guidance**: [yes | no]
-- **Guidance Needed For**: [plugins | tools | both | none]
-
-## Recommendations
-
-1. [recommendation 1]
-2. [recommendation 2]
-
-## Merge Decisions (if applicable)
-
-### Plugin Merge
-- [decision and rationale]
-
-### Tool Merge
-- [decision and rationale]