opencode-architect 0.2.0

package/assets/templates/installer.template.txt

@@ -0,0 +1,269 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+EXTENSION NAME
+  "myextension"  → your extension identifier (e.g., "mytool")
+
+SKILL NAME
+  "myextension"  → must match the folder name in assets/skills/
+
+COMMAND NAME
+  "my-command.md" → your command file name in assets/commands/
+
+PACKAGE NAME
+  "opencode-myextension" → your npm package name
+
+---
+import { exists, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Scope = "local" | "global";
+
+export interface InstallOptions {
+  configurePermission?: boolean;
+  configureMcp?: boolean;
+  addPluginConfig?: boolean;
+}
+
+export interface InstallResult {
+  scope: Scope;
+  skillPath: string;
+  commandPath: string;
+  configPath: string;
+  migrated: boolean;
+  permissionConfigured: boolean;
+  mcpConfigured: boolean;
+  pluginAdded: boolean;
+}
+
+export interface UninstallResult {
+  scope: Scope;
+  removed: string[];
+  pluginRemoved: boolean;
+}
+
+export interface StatusResult {
+  local: { installed: boolean; version: string | null; pluginInConfig: boolean } | null;
+  global: { installed: boolean; version: string | null; pluginInConfig: boolean } | null;
+}
+
+const SKILL_NAME = "myextension";
+const COMMAND_NAME = "my-command.md";
+const PLUGIN_NAME = "opencode-myextension";
+
+export async function getPackageVersion(): Promise<string> {
+  const content = await Bun.file(`${import.meta.dirname}/../package.json`).text();
+  return JSON.parse(content).version;
+}
+
+export async function getPackageName(): Promise<string> {
+  const content = await Bun.file(`${import.meta.dirname}/../package.json`).text();
+  return JSON.parse(content).name;
+}
+
+function getPackageDir(): string {
+  return join(import.meta.dirname, "..");
+}
+
+export function getGlobalConfigPath(): string {
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  if (xdgConfig) {
+    return join(xdgConfig, "opencode");
+  }
+  return join(homedir(), ".config", "opencode");
+}
+
+export function getLocalConfigPath(projectDir: string): string {
+  return join(projectDir, ".opencode");
+}
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  for (const entry of await readdir(src, { withFileTypes: true })) {
+    const s = join(src, entry.name);
+    const d = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(s, d);
+    } else {
+      await Bun.write(d, Bun.file(s));
+    }
+  }
+}
+
+async function readJsonConfig(path: string): Promise<Record<string, unknown>> {
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+async function writeJsonConfig(path: string, config: Record<string, unknown>): Promise<void> {
+  await mkdir(join(path, ".."), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2));
+}
+
+async function ensureSkillPermission(configPath: string): Promise<void> {
+  const config = await readJsonConfig(configPath);
+  if (!config.permission) config.permission = {};
+  if (!(config.permission as Record<string, unknown>).skill) (config.permission as Record<string, unknown>).skill = {};
+  const skillPerms = (config.permission as Record<string, unknown>).skill as Record<string, unknown>;
+  if (skillPerms[SKILL_NAME] !== "allow") {
+    skillPerms[SKILL_NAME] = "allow";
+    await mkdir(join(configPath, ".."), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+  }
+}
+
+async function removeSkillPermission(configPath: string): Promise<void> {
+  const config = await readJsonConfig(configPath);
+  if (config.permission && (config.permission as Record<string, unknown>).skill) {
+    const skillPerms = (config.permission as Record<string, unknown>).skill as Record<string, unknown>;
+    delete skillPerms[SKILL_NAME];
+    if (Object.keys(skillPerms).length === 0) delete (config.permission as Record<string, unknown>).skill;
+    if (Object.keys(config.permission as Record<string, unknown>).length === 0) delete config.permission;
+    await mkdir(join(configPath, ".."), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+  }
+}
+
+async function addPluginToConfig(configPath: string, pluginName: string): Promise<boolean> {
+  const config = await readJsonConfig(configPath);
+  if (!config.plugin) config.plugin = [];
+  const plugins = config.plugin as string[];
+  if (plugins.includes(pluginName)) return false;
+  plugins.push(pluginName);
+  config.plugin = plugins;
+  await mkdir(join(configPath, ".."), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2));
+  return true;
+}
+
+async function removePluginFromConfig(configPath: string, pluginName: string): Promise<boolean> {
+  const config = await readJsonConfig(configPath);
+  if (!config.plugin) return false;
+  const plugins = config.plugin as string[];
+  const index = plugins.indexOf(pluginName);
+  if (index === -1) return false;
+  plugins.splice(index, 1);
+  if (plugins.length === 0) delete config.plugin;
+  else config.plugin = plugins;
+  await mkdir(join(configPath, ".."), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2));
+  return true;
+}
+
+async function isPluginInConfig(configPath: string, pluginName: string): Promise<boolean> {
+  const config = await readJsonConfig(configPath);
+  if (!config.plugin) return false;
+  return (config.plugin as string[]).includes(pluginName);
+}
+
+async function addMcpServer(configPath: string): Promise<boolean> {
+  return false;
+}
+
+export async function checkMigrationNeeded(projectDir: string): Promise<{
+  needed: boolean;
+  rootConfigPath: string;
+  dotOpenencodeConfigPath: string;
+  rootConfig: Record<string, unknown> | null;
+  dotOpenencodeConfig: Record<string, unknown> | null;
+}> {
+  const rootConfigPath = join(projectDir, "opencode.json");
+  const dotOpenencodeConfigPath = join(projectDir, ".opencode", "opencode.json");
+  const rootExists = await exists(rootConfigPath);
+  const dotOpenencodeExists = await exists(dotOpenencodeConfigPath);
+  if (!rootExists) return { needed: false, rootConfigPath, dotOpenencodeConfigPath, rootConfig: null, dotOpenencodeConfig: null };
+  const rootConfig = await readJsonConfig(rootConfigPath);
+  const dotOpenencodeConfig = dotOpenencodeExists ? await readJsonConfig(dotOpenencodeConfigPath) : null;
+  return { needed: rootExists, rootConfigPath, dotOpenencodeConfigPath, rootConfig, dotOpenencodeConfig };
+}
+
+export async function migrateRootConfig(
+  projectDir: string,
+  onConflict?: (root: Record<string, unknown>, dot: Record<string, unknown>) => Promise<boolean>
+): Promise<boolean> {
+  const { needed, rootConfigPath, dotOpenencodeConfigPath, rootConfig, dotOpenencodeConfig } = await checkMigrationNeeded(projectDir);
+  if (!needed || !rootConfig) return false;
+  if (dotOpenencodeConfig) {
+    const hasConflict = Object.keys(rootConfig).some(key => key in dotOpenencodeConfig);
+    if (hasConflict && onConflict) {
+      const shouldContinue = await onConflict(rootConfig, dotOpenencodeConfig);
+      if (!shouldContinue) return false;
+    }
+    const merged = { ...rootConfig, ...dotOpenencodeConfig };
+    await writeJsonConfig(dotOpenencodeConfigPath, merged);
+  } else {
+    await mkdir(join(projectDir, ".opencode"), { recursive: true });
+    await writeJsonConfig(dotOpenencodeConfigPath, rootConfig);
+  }
+  await rm(rootConfigPath);
+  return true;
+}
+
+export async function install(
+  scope: Scope,
+  projectDir: string = process.cwd(),
+  options: InstallOptions = {}
+): Promise<InstallResult> {
+  const version = await getPackageVersion();
+  const packageName = await getPackageName();
+  const pkgDir = getPackageDir();
+  const { configurePermission = true, configureMcp = true, addPluginConfig = true } = options;
+  const configBase = scope === "global" ? getGlobalConfigPath() : getLocalConfigPath(projectDir);
+  const skillPath = join(configBase, "skills", SKILL_NAME);
+  const commandPath = join(configBase, "commands", COMMAND_NAME);
+  const configPath = join(configBase, "opencode.json");
+  const versionMarker = join(skillPath, ".version");
+  let migrated = false;
+  if (scope === "local") migrated = await migrateRootConfig(projectDir);
+  await copyDir(join(pkgDir, "assets", "skills", SKILL_NAME), skillPath);
+  await mkdir(join(configBase, "commands"), { recursive: true });
+  await Bun.write(commandPath, Bun.file(join(pkgDir, "assets", "commands", COMMAND_NAME)));
+  await Bun.write(versionMarker, version);
+  let permissionConfigured = false;
+  if (configurePermission) { await ensureSkillPermission(configPath); permissionConfigured = true; }
+  let mcpConfigured = false;
+  if (configureMcp) mcpConfigured = await addMcpServer(configPath);
+  let pluginAdded = false;
+  if (addPluginConfig) pluginAdded = await addPluginToConfig(configPath, packageName);
+  return { scope, skillPath, commandPath, configPath, migrated, permissionConfigured, mcpConfigured, pluginAdded };
+}
+
+export async function uninstall(scope: Scope, projectDir: string = process.cwd()): Promise<UninstallResult> {
+  const packageName = await getPackageName();
+  const configBase = scope === "global" ? getGlobalConfigPath() : getLocalConfigPath(projectDir);
+  const skillPath = join(configBase, "skills", SKILL_NAME);
+  const commandPath = join(configBase, "commands", COMMAND_NAME);
+  const configPath = join(configBase, "opencode.json");
+  const removed: string[] = [];
+  if (await exists(skillPath)) { await rm(skillPath, { recursive: true }); removed.push(skillPath); }
+  if ( await exists(commandPath)) { await rm(commandPath); removed.push(commandPath); }
+  let pluginRemoved = false;
+  if (await exists(configPath)) { await removeSkillPermission(configPath); pluginRemoved = await removePluginFromConfig(configPath, packageName); }
+  const skillsDir = join(configBase, "skills");
+  const commandsDir = join(configBase, "commands");
+  try { const skillsContents = await readdir(skillsDir); if (skillsContents.length === 0) await rm(skillsDir, { recursive: true }); } catch {}
+  try { const commandsContents = await readdir(commandsDir); if (commandsContents.length === 0) await rm(commandsDir, { recursive: true }); } catch {}
+  return { scope, removed, pluginRemoved };
+}
+
+export async function status(projectDir: string = process.cwd()): Promise<StatusResult> {
+  const version = await getPackageVersion();
+  const packageName = await getPackageName();
+  const localConfigPath = getLocalConfigPath(projectDir);
+  const localVersionMarker = join(localConfigPath, "skills", SKILL_NAME, ".version");
+  const localConfigFile = join(localConfigPath, "opencode.json");
+  const globalConfigPath = getGlobalConfigPath();
+  const globalVersionMarker = join(globalConfigPath, "skills", SKILL_NAME, ".version");
+  const globalConfigFile = join(globalConfigPath, "opencode.json");
+  let localStatus: { installed: boolean; version: string | null; pluginInConfig: boolean } | null = null;
+  let globalStatus: { installed: boolean; version: string | null; pluginInConfig: boolean } | null = null;
+  try { const localVersion = (await readFile(localVersionMarker, "utf-8")).trim(); const localPluginInConfig = await isPluginInConfig(localConfigFile, packageName); localStatus = { installed: true, version: localVersion, pluginInConfig: localPluginInConfig }; } catch { const skillPath = join(localConfigPath, "skills", SKILL_NAME); if (await exists(skillPath)) { const localPluginInConfig = await isPluginInConfig(localConfigFile, packageName); localStatus = { installed: true, version: null, pluginInConfig: localPluginInConfig }; } }
+  try { const globalVersion = (await readFile(globalVersionMarker, "utf-8")).trim(); const globalPluginInConfig = await isPluginInConfig(globalConfigFile, packageName); globalStatus = { installed: true, version: globalVersion, pluginInConfig: globalPluginInConfig }; } catch { const skillPath = join(globalConfigPath, "skills", SKILL_NAME); if (await exists(skillPath)) { const globalPluginInConfig = await isPluginInConfig(globalConfigFile, packageName); globalStatus = { installed: true, version: null, pluginInConfig: globalPluginInConfig }; } }
+  return { local: localStatus, global: globalStatus };
+}

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

@@ -0,0 +1,60 @@
+# 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]

package/assets/templates/package-basics.template.json

@@ -0,0 +1,28 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+PACKAGE NAME
+  "opencode-myextension"     → your extension name (e.g., "opencode-mytool")
+  "myextension"              → skill/extension identifier (e.g., "mytool")
+
+VERSION
+  "1.0.0"                    → initial version
+
+PATHS
+  "skills/myextension"       → path to your skill assets
+  "commands/my-command.md"   → path to your command file
+
+METADATA
+  "Publisher Name"           → your name or organization
+  "email@example.com"        → your email
+  "https://github.com/org/opencode-myextension.git" → your repo URL
+
+---
+{
+  "name": "opencode-myextension",
+  "version": "1.0.0",
+  "type": "module",
+  "module": "index.ts",
+  "files": ["index.ts", "plugin.ts", "assets"]
+}

package/assets/templates/package-full.template.json

@@ -0,0 +1,56 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+PACKAGE NAME
+  "opencode-myextension"     → your extension name (e.g., "opencode-mytool")
+  "myextension"              → skill/extension identifier (e.g., "mytool")
+
+VERSION
+  "1.0.0"                    → initial version
+
+PATHS
+  "skills/myextension"       → path to your skill assets
+  "commands/my-command.md"   → path to your command file
+
+METADATA
+  "Publisher Name"           → your name or organization
+  "Author Name <email@example.com>" → your name and email
+  "email@example.com"        → your support email
+  "https://github.com/org/opencode-myextension.git" → your repo URL
+
+---
+{
+  "name": "opencode-myextension",
+  "version": "1.0.0",
+  "type": "module",
+  "module": "index.ts",
+  "bin": {
+    "opencode-myextension": "./src/cli.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/org/opencode-myextension.git"
+  },
+  "publisher": "Publisher Name",
+  "author": "Author Name <email@example.com>",
+  "bugs": {
+    "url": "https://github.com/org/opencode-myextension/issues",
+    "email": "support@example.com"
+  },
+  "license": "MIT",
+  "files": ["index.ts", "plugin.ts", "src", "assets"],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@opencode-ai/plugin": "*",
+    "@opencode-ai/sdk": "^1.2.20"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/assets/templates/plugin-local.template.txt

@@ -0,0 +1,69 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+EXTENSION NAME
+  "myextension"  → your extension identifier (e.g., "mytool")
+
+SKILL NAME
+  "myextension"  → must match the folder name in assets/skills/
+
+COMMAND NAME
+  "my-command.md" → your command file name in assets/commands/
+
+PACKAGE NAME
+  "./src/installer.ts" → path to installer module (for published packages)
+  Or inline install functions (for local packages)
+
+---
+import type { Plugin } from "@opencode-ai/plugin";
+import { install, getGlobalConfigPath, getPackageVersion, type Scope } from "./src/installer.ts";
+import { join } from "node:path";
+
+const plugin: Plugin = async ({ directory }) => ({
+  config: async () => {
+    const version = await getPackageVersion();
+    const globalConfigPath = getGlobalConfigPath();
+    const globalVersionMarker = join(globalConfigPath, "skills", "myextension", ".version");
+
+    const isGlobalInstall = directory === globalConfigPath || 
+      directory.startsWith(globalConfigPath + "/") ||
+      directory.startsWith(globalConfigPath + "\\");
+
+    let scope: Scope;
+    
+    if (isGlobalInstall) {
+      scope = "global";
+    } else {
+      try {
+        const globalVersion = (await Bun.file(globalVersionMarker).text()).trim();
+        if (globalVersion === version) {
+          return;
+        }
+      } catch {}
+      scope = "local";
+    }
+
+    const marker = scope === "global"
+      ? globalVersionMarker
+      : join(directory, ".opencode", "skills", "myextension", ".version");
+
+    try {
+      const installedVersion = (await Bun.file(marker).text()).trim();
+      if (installedVersion === version) {
+        return;
+      }
+    } catch {}
+
+    const result = await install(scope, directory);
+    
+    console.log(`\nOpenCode MyExtension installed ${scope === "global" ? "globally" : "locally"}:`);
+    console.log(`  Skill: ${result.skillPath}`);
+    console.log(`  Command: ${result.commandPath}`);
+    if (result.migrated) {
+      console.log(`  Migrated: opencode.json → .opencode/opencode.json`);
+    }
+  },
+});
+
+export default plugin;

package/assets/templates/prompts.template.txt

@@ -0,0 +1,28 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+EXTENSION NAME
+  "myextension"  → your extension identifier
+
+SKILL NAME
+  "myextension"  → must match the skill folder name
+
+---
+import { confirm } from "@inquirer/prompts";
+
+export async function confirmOverwrite(message: string): Promise<boolean> {
+  return confirm({ message, default: false });
+}
+
+export async function confirmPermissionConfig(): Promise<boolean> {
+  return confirm({ message: "Configure skill permission (allow myextension)?", default: true });
+}
+
+export async function confirmMcpConfig(): Promise<boolean> {
+  return confirm({ message: "Configure MCP server?", default: true });
+}
+
+export async function confirmPluginConfig(): Promise<boolean> {
+  return confirm({ message: "Add plugin to opencode.json config?", default: true });
+}

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

@@ -0,0 +1,46 @@
+TEMPLATE INSTRUCTIONS
+====================
+Replace the following placeholders before use:
+
+EXTENSION NAME
+  "myextension"  → your extension identifier
+
+VERSION
+  "1.0.0"        → initial version
+
+TOPICS
+  "topic1"       → your skill topics
+  "topic2"
+
+DESCRIPTION
+  "Use this skill when the user asks about..." → your skill description
+
+---
+---
+name: myextension
+description: Use this skill when the user asks about...
+license: MIT
+compatibility: opencode
+metadata:
+  version: 1.0.0
+  audience: agents
+  topic: [topic1, topic2]
+---
+
+## Activation Triggers
+
+**USE this skill when user asks about:**
+- Category: "Example query"
+
+**DO NOT USE for:**
+- Non-technical topics
+- Known specific repos
+
+## Workflow Summary
+
+<workflow>
+<phase name="detect">Check available tools</phase>
+<phase name="search">Execute search</phase>
+<phase name="query">Query sources</phase>
+<phase name="synthesize">Return answer</phase>
+</workflow>

package/assets/templates/tsconfig.template.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "module": "esnext",
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["bun-types"]
+  },
+  "include": ["*.ts", "src/**/*.ts", "tests/**/*.ts"]
+}

package/commands/sync-docs.ts

@@ -0,0 +1,9 @@
+import type { Config } from "@opencode-ai/sdk";
+
+export const command: NonNullable<Config["command"]>[string] = {
+  description: "Sync OpenCode docs into ~/.cache/opencode/opencode-architect/docs",
+  template:
+    "Use the sync-docs tool to fetch the latest OpenCode documentation into `~/.cache/opencode/opencode-architect/docs`.",
+};
+
+export default command;