opencode-architect 0.2.4 → 0.4.0

package/assets/templates/skill-structure.template.md

@@ -24,7 +24,7 @@ compatibility: opencode
 metadata:
   version: 1.0.0
   audience: agents
-  topic: [topic1, topic2]
+  topic: "topic1, topic2"
 ---
 
 ## Activation Triggers
@@ -32,9 +32,9 @@ metadata:
 **USE this skill when user asks about:**
 - Category: "Example query"
 
-**DO NOT USE for:**
-- Non-technical topics
-- Known specific repos
+**Route elsewhere when:**
+- The topic is non-technical
+- The repo is well-known and already documented
 
 ## Workflow Summary
 

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/index.ts

@@ -1,120 +1,21 @@
-import type { Plugin, PluginInput } from "@opencode-ai/plugin";
-import { readFile } from "node:fs/promises";
+import type { Plugin } from "@opencode-ai/plugin";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import type { AgentConfig } from "@opencode-ai/sdk";
-import { command as syncDocsCommand } from "./commands/sync-docs";
-import { OpenCodeDocsFetcher } from "./scripts/fetch-opencode-docs";
-import { SilentLogger } from "./scripts/logger";
-import { createSyncDocsTool } from "./tools/sync-docs";
+import { AgentLoader } from "./agent-loader";
 
 const AGENTS_DIR = path.join(import.meta.dirname, "assets", "agents");
 
-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
-
-interface AgentFrontmatter {
-  description: string;
-  mode: "primary" | "subagent" | "all";
-  tools?: Record<string, boolean>;
-  permission?: {
-    edit?: "ask" | "allow" | "deny";
-    bash?: ("ask" | "allow" | "deny") | Record<string, "ask" | "allow" | "deny">;
-    webfetch?: "ask" | "allow" | "deny";
-    doom_loop?: "ask" | "allow" | "deny";
-    external_directory?: "ask" | "allow" | "deny";
-  };
-}
-
-async function parseAgentMarkdown(content: string, agentName: string): Promise<AgentConfig> {
-  const match = content.match(FRONTMATTER_REGEX);
-
-  if (!match || match.length < 3) {
-    throw new Error(`Agent ${agentName} must have YAML frontmatter`);
-  }
-
-  const frontmatterYaml = match[1] as string;
-  const rawPrompt = match[2] as string;
-  const frontmatter = parseYaml(frontmatterYaml) as AgentFrontmatter;
-  const prompt = rawPrompt.replace(/^\r?\n/, "");
-
-  const config: AgentConfig = {
-    description: frontmatter.description,
-    mode: frontmatter.mode,
-    prompt,
-  };
-
-  if (frontmatter.tools) {
-    config.tools = frontmatter.tools;
-  }
-
-  if (frontmatter.permission) {
-    config.permission = frontmatter.permission;
-  }
-
-  return config;
-}
-
-const OpencodeArchitect: Plugin = async (input) => {
-  const syncDocsTool = createSyncDocsTool();
-
-  syncDocsOnStartup(input.client);
-
-  const agents = await loadAgents();
+const OpencodeArchitect: Plugin = async () => {
+  const agents = await new AgentLoader(AGENTS_DIR).loadAgents();
 
   return {
     config: async (config) => {
       config.agent = config.agent || {};
-      config.command = config.command || {};
 
       for (const [name, agentConfig] of Object.entries(agents)) {
         config.agent[name] = agentConfig;
       }
-
-      config.command["sync-docs"] = syncDocsCommand;
-    },
-    tool: {
-      "sync-docs": syncDocsTool,
     },
   };
 };
 
 export default OpencodeArchitect;
-
-async function loadAgents(): Promise<Record<string, AgentConfig>> {
-  const agentFiles = [
-    "opencode-agent-designer.md",
-    "opencode-architect.md",
-    "opencode-command-crafter.md",
-    "opencode-extension-auditor.md",
-    "opencode-packager.md",
-    "opencode-publisher.md",
-    "opencode-mcp-integrator.md",
-    "opencode-plugin-engineer.md",
-    "opencode-skill-creator.md",
-    "opencode-tool-builder.md",
-  ];
-
-  const agents: Record<string, AgentConfig> = {};
-
-  for (const filename of agentFiles) {
-    const agentPath = path.join(AGENTS_DIR, filename);
-    const agentContent = await readFile(agentPath, "utf-8");
-    const agentName = path.basename(filename, ".md");
-    agents[agentName] = await parseAgentMarkdown(agentContent, agentName);
-  }
-
-  return agents;
-}
-
-function syncDocsOnStartup(client: PluginInput["client"]): void {
-  const fetcher = new OpenCodeDocsFetcher(new SilentLogger());
-  fetcher.run().catch((error: unknown) => {
-    const message = error instanceof Error ? error.message : String(error);
-    client.tui.showToast({
-      body: {
-        message: `Failed to sync OpenCode docs: ${message}`,
-        variant: "error",
-      },
-    });
-  });
-}

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,28 +1,50 @@
 {
   "name": "opencode-architect",
-  "version": "0.2.4",
+  "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": "https://github.com/diegohb/opencode-architect.git"
+    "url": "git+https://github.com/Expert-Vision-Software/opencode-architect.git"
   },
+  "homepage": "https://github.com/Expert-Vision-Software/opencode-architect#readme",
   "publisher": "Expert Vision Software",
   "author": "Expert Vision Support <support@expertvision.software>",
   "bugs": {
-    "url": "https://github.com/diegohb/opencode-architect/issues",
+    "url": "https://github.com/Expert-Vision-Software/opencode-architect/issues",
     "email": "support@expertvision.software"
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "test": "bun test",
     "release": "npm version patch && npm publish && git push --follow-tags"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "index.ts",
-    "tools",
-    "commands",
-    "scripts",
+    "agent-loader.ts",
+    "cli.ts",
+    "installer.ts",
     "assets"
   ],
   "dependencies": {
@@ -30,9 +52,9 @@
     "@opencode-ai/plugin": "*"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "latest",
     "@opencode-ai/sdk": "latest",
     "@types/bun": "latest",
-    "@types/node": "latest"
+    "@types/node": "latest",
+    "typescript": "latest"
   }
 }