@oh-my-tool/cli 0.2.0

package/src/integration/types.ts

@@ -0,0 +1,55 @@
+export type AgentId = "codex" | "omp" | "qoder" | "pi" | "cursor" | "claude";
+
+export const AGENT_IDS: readonly AgentId[] = [
+  "codex",
+  "omp",
+  "qoder",
+  "pi",
+  "cursor",
+  "claude",
+];
+export type IntegrationStatus =
+  | "not-installed"
+  | "installed"
+  | "current"
+  | "update-available"
+  | "broken"
+  | "conflict"
+  | "repaired"
+  | "uninstalled";
+
+export interface AgentDetection {
+  id: AgentId;
+  displayName: string;
+  command: string;
+  target: string;
+  variant?: string;
+}
+
+export interface IntegrationResult {
+  agent: AgentId;
+  displayName: string;
+  target: string;
+  status: IntegrationStatus;
+  detail?: string;
+}
+
+export interface ManagedAgentState {
+  target: string;
+  canonical: string;
+  version: string;
+  digest: string;
+  mode: "junction" | "symlink";
+  backup?: string;
+}
+
+export interface IntegrationState {
+  schemaVersion: 1;
+  skills: {
+    "oh-my-tool"?: {
+      version: string;
+      digest: string;
+      agents: Partial<Record<AgentId, ManagedAgentState>>;
+    };
+  };
+}

package/src/migration.ts

@@ -0,0 +1,44 @@
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { OhMyToolPaths } from "./paths";
+
+export type MigrationStatus =
+  | "migrated"
+  | "skipped-custom-home"
+  | "skipped-no-legacy"
+  | "skipped-destination-exists";
+
+export interface MigrationResult {
+  readonly status: MigrationStatus;
+  readonly legacyHome: string;
+  readonly home: string;
+  readonly legacyPreserved: true;
+}
+
+const KNOWN_STATE = ["config.toml", "extensions", "integrations", "cache", "logs"];
+
+export async function migrateLegacyHome(paths: OhMyToolPaths): Promise<MigrationResult> {
+  const base = { legacyHome: paths.legacyHome, home: paths.home, legacyPreserved: true as const };
+  if (paths.isCustomHome) return { ...base, status: "skipped-custom-home" };
+  if (!existsSync(paths.legacyHome)) return { ...base, status: "skipped-no-legacy" };
+  if (existsSync(paths.home)) return { ...base, status: "skipped-destination-exists" };
+
+  mkdirSync(paths.home, { recursive: true });
+  for (const name of KNOWN_STATE) {
+    const source = join(paths.legacyHome, name);
+    if (!existsSync(source)) continue;
+    const destination = join(paths.home, name);
+    mkdirSync(dirname(destination), { recursive: true });
+    cpSync(source, destination, { recursive: true, errorOnExist: true });
+  }
+  return { ...base, status: "migrated" };
+}
+
+export async function prepareHome(paths: OhMyToolPaths): Promise<MigrationResult> {
+  const migration = await migrateLegacyHome(paths);
+  mkdirSync(paths.home, { recursive: true });
+  for (const directory of [paths.extensions, paths.integrations, dirname(paths.audit)]) {
+    mkdirSync(directory, { recursive: true });
+  }
+  return migration;
+}

package/src/paths.ts

@@ -0,0 +1,41 @@
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+
+export interface CreatePathsOptions {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  userHome?: string;
+}
+
+export interface OhMyToolPaths {
+  readonly userHome: string;
+  readonly home: string;
+  readonly legacyHome: string;
+  readonly config: string;
+  readonly extensions: string;
+  readonly integrations: string;
+  readonly cache: string;
+  readonly audit: string;
+  readonly isCustomHome: boolean;
+}
+
+export function createPaths(options: CreatePathsOptions = {}): OhMyToolPaths {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const userHome = options.userHome ?? homedir();
+  const path = platform === "win32" ? win32 : posix;
+  const customHome = env.OH_MY_TOOL_HOME;
+  const home = customHome || path.join(userHome, ".oh-my-tool");
+  const legacyHome = path.join(userHome, ".omt");
+  return {
+    userHome,
+    home,
+    legacyHome,
+    config: path.join(home, "config.toml"),
+    extensions: path.join(home, "extensions"),
+    integrations: path.join(home, "integrations"),
+    cache: path.join(home, "cache"),
+    audit: path.join(home, "logs", "audit.jsonl"),
+    isCustomHome: Boolean(customHome),
+  };
+}

package/src/policy/policy.ts

@@ -0,0 +1,139 @@
+import type { Config } from "../config/config";
+import { getConnectionConfig } from "../config/config";
+
+export class PolicyError extends Error {
+  readonly code = "POLICY_VIOLATION";
+}
+
+const FORBIDDEN = /(?:^|[^a-z_])(insert|update|delete|drop|alter|create|truncate|rename|grant|revoke|replace|call|set|commit|rollback|load\s+data|lock\s+tables|unlock\s+tables|create\s+database|drop\s+database)(?:[^a-z_]|$)/i;
+
+function stripLiteralsAndComments(sql: string): string {
+  let out = "";
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const ch = sql[i];
+    const next = sql[i + 1];
+    // line comments
+    if (ch === "-" && next === "-") {
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "#") {
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    // block comments
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    // string literals
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      i++;
+      while (i < n) {
+        if (sql[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (sql[i] === quote) {
+          if (sql[i + 1] === quote) {
+            i += 2;
+            continue;
+          }
+          i++;
+          break;
+        }
+        i++;
+      }
+      out += " ";
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
+function countStatements(sql: string): number {
+  const cleaned = stripLiteralsAndComments(sql);
+  const parts = cleaned
+    .split(";")
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+  return parts.length;
+}
+
+export function assertReadOnly(sql: string): void {
+  if (typeof sql !== "string" || sql.trim().length === 0) {
+    throw new PolicyError("sql must be a non-empty string");
+  }
+  if (countStatements(sql) > 1) {
+    throw new PolicyError("only a single read-only statement is allowed");
+  }
+  const cleaned = stripLiteralsAndComments(sql);
+  if (FORBIDDEN.test(cleaned)) {
+    throw new PolicyError("sql contains a non read-only statement");
+  }
+}
+
+const FORBIDDEN_INPUT = new Set([
+  "host",
+  "username",
+  "password",
+  "port",
+  "database",
+  "secret",
+  "tls",
+]);
+
+export function validateConnectionInput(
+  input: Record<string, unknown>,
+  config: Config,
+  extensionId: string,
+): void {
+  for (const key of FORBIDDEN_INPUT) {
+    if (key in input && input[key] !== undefined && input[key] !== null) {
+      throw new PolicyError(`agent input must not contain '${key}'`);
+    }
+  }
+  const connection = input["connection"];
+  if (typeof connection !== "string" || connection.length === 0) {
+    throw new PolicyError("input must specify a configured 'connection' name");
+  }
+  if (!getConnectionConfig(config, extensionId, connection)) {
+    throw new PolicyError(`unknown connection '${connection}' for extension '${extensionId}'`);
+  }
+}
+
+export interface Limits {
+  maxRows: number;
+  timeoutMs: number;
+}
+
+export const DEFAULT_MAX_ROWS = 100;
+export const MAX_MAX_ROWS = 1000;
+export const DEFAULT_TIMEOUT_MS = 5000;
+export const MAX_TIMEOUT_MS = 30000;
+
+export function applyLimits(input: Record<string, unknown>): Limits {
+  const maxRows = clamp(
+    typeof input.maxRows === "number" ? input.maxRows : DEFAULT_MAX_ROWS,
+    1,
+    MAX_MAX_ROWS,
+  );
+  const timeoutMs = clamp(
+    typeof input.timeoutMs === "number" ? input.timeoutMs : DEFAULT_TIMEOUT_MS,
+    1,
+    MAX_TIMEOUT_MS,
+  );
+  return { maxRows, timeoutMs };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+

package/src/runtime/errors.ts

@@ -0,0 +1,8 @@
+export class RuntimeError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = "RuntimeError";
+  }
+}
+
+export { RuntimeError as OmtError };

package/src/runtime/executor.ts

@@ -0,0 +1,66 @@
+import type { Logger, SecretStore } from "@oh-my-tool/sdk";
+import type { ToolDescriptor, ToolProvider } from "./provider";
+import type { ExecutionContext } from "./provider";
+import type { ExecutionResult } from "./result";
+import { validateInput } from "./schema";
+
+export interface PolicyPreflight {
+  preflight(descriptor: ToolDescriptor, input: Record<string, unknown>): void | Promise<void>;
+}
+
+export type CreateExecutionContext = (
+  descriptor: ToolDescriptor,
+  input: Record<string, unknown>,
+) => ExecutionContext | Promise<ExecutionContext>;
+
+export interface RuntimeExecutionDeps {
+  descriptor: ToolDescriptor;
+  provider: ToolProvider;
+  policy: PolicyPreflight;
+  createExecutionContext: CreateExecutionContext;
+}
+
+const noopLogger: Logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const emptySecrets: SecretStore = {
+  async get() { return undefined; },
+  async set() {},
+  async delete() {},
+};
+
+export async function executeRuntimeTool(
+  deps: RuntimeExecutionDeps,
+  rawInput: Record<string, unknown>,
+): Promise<ExecutionResult> {
+  try {
+    const input = validateInput(deps.descriptor.inputSchema as any, rawInput);
+    await deps.policy.preflight(deps.descriptor, input);
+    const context = await deps.createExecutionContext(deps.descriptor, input);
+    const result = await deps.provider.execute(deps.descriptor.id, input, context);
+    return {
+      ok: true,
+      toolId: deps.descriptor.id,
+      output: result.data,
+      meta: result.meta ?? {},
+    };
+  } catch (error) {
+    const typed = error as { code?: string; message?: string };
+    return {
+      ok: false,
+      toolId: deps.descriptor.id,
+      error: {
+        code: typed.code ?? "EXECUTION_FAILED",
+        message: typed.message ?? String(error),
+      },
+    };
+  }
+}
+
+export function defaultExecutionContext(): ExecutionContext {
+  return { logger: noopLogger, config: {}, secrets: emptySecrets };
+}

package/src/runtime/provider-registry.ts

@@ -0,0 +1,23 @@
+import type { ToolProvider } from "./provider";
+import { RuntimeError } from "./errors";
+
+export class ProviderRegistry {
+  private readonly providers = new Map<string, ToolProvider>();
+
+  register(provider: ToolProvider): void {
+    if (this.providers.has(provider.id)) {
+      throw new RuntimeError("DUPLICATE_PROVIDER_ID", `duplicate provider '${provider.id}'`);
+    }
+    this.providers.set(provider.id, provider);
+  }
+
+  get(id: string): ToolProvider | undefined {
+    return this.providers.get(id);
+  }
+
+  require(id: string): ToolProvider {
+    const provider = this.get(id);
+    if (!provider) throw new RuntimeError("PROVIDER_NOT_FOUND", `provider '${id}' was not found`);
+    return provider;
+  }
+}

package/src/runtime/provider.ts

@@ -0,0 +1,29 @@
+import type { SecretStore, Logger } from "@oh-my-tool/sdk";
+import type { ToolResult } from "./result";
+
+export interface ToolDescriptor {
+  id: string;
+  description: string;
+  keywords?: string[];
+  risk: "read" | "write" | "admin";
+  inputSchema?: Record<string, unknown>;
+  provider: { id: string; kind: string };
+  source: { id: string; kind: string };
+}
+
+export type ToolSearchResult = Omit<ToolDescriptor, "inputSchema">;
+
+export interface ExecutionContext {
+  logger: Logger;
+  config: Record<string, unknown>;
+  secrets: SecretStore;
+}
+
+export interface ToolProvider {
+  readonly id: string;
+  readonly kind: string;
+  listTools(): Promise<readonly ToolDescriptor[]>;
+  execute(toolId: string, input: unknown, context: ExecutionContext): Promise<ToolResult>;
+}
+
+export type { ToolResult } from "./result";

package/src/runtime/providers/native/discovery.ts

@@ -0,0 +1,2 @@
+export { discoverExtensions } from "../../../extension/discovery";
+export type { InstalledExtension } from "../../../extension/discovery";

package/src/runtime/providers/native/install.ts

@@ -0,0 +1,2 @@
+export { installLocalExtension } from "../../../extension/install";
+export type { InstalledRef } from "../../../extension/install";

package/src/runtime/providers/native/loader.ts

@@ -0,0 +1 @@
+export { loadExtension } from "../../../extension/loader";

package/src/runtime/providers/native/manifest.ts

@@ -0,0 +1,6 @@
+export {
+  parseManifest,
+  validateManifest,
+  validateHandlers,
+  checkSdkCompatibility,
+} from "../../../extension/manifest";

package/src/runtime/providers/native/provider.ts

@@ -0,0 +1,57 @@
+import { discoverExtensions, type InstalledExtension } from "../../../extension/discovery";
+import { loadExtension } from "../../../extension/loader";
+import type { OhMyToolPaths } from "../../../paths";
+import type { ExecutionContext, ToolDescriptor, ToolProvider } from "../../provider";
+import type { ToolResult } from "../../result";
+
+export class NativeExtensionProvider implements ToolProvider {
+  readonly id = "native";
+  readonly kind = "native";
+
+  constructor(private readonly homeOrPaths: string | Pick<OhMyToolPaths, "home">) {}
+
+  private home(): string {
+    return typeof this.homeOrPaths === "string" ? this.homeOrPaths : this.homeOrPaths.home;
+  }
+
+  async listTools(): Promise<readonly ToolDescriptor[]> {
+    const descriptors: ToolDescriptor[] = [];
+    for (const extension of discoverExtensions(this.home())) {
+      for (const tool of extension.manifest.tools) {
+        descriptors.push({
+          id: tool.name,
+          description: tool.description,
+          // Preserve extension-level discovery terms from the legacy search
+          // contract while keeping ToolRegistry independent of manifests.
+          keywords: [...new Set([
+            ...(tool.keywords ?? []),
+            extension.manifest.id,
+            extension.manifest.name,
+            ...(extension.manifest.keywords ?? []),
+          ])],
+          risk: tool.risk ?? "read",
+          inputSchema: tool.inputSchema,
+          provider: { id: this.id, kind: this.kind },
+          source: { id: extension.manifest.id, kind: "extension" },
+        });
+      }
+    }
+    return descriptors;
+  }
+
+  async execute(toolId: string, input: unknown, context: ExecutionContext): Promise<ToolResult> {
+    const extension = this.findExtension(toolId);
+    const definition = await loadExtension(extension);
+    const handler = definition.handlers[toolId];
+    if (!handler) throw new Error(`no handler for ${toolId}`);
+    return handler({ toolName: toolId, logger: context.logger, config: context.config, secrets: context.secrets }, input);
+  }
+
+  private findExtension(toolId: string): InstalledExtension {
+    const extension = discoverExtensions(this.home()).find((candidate) =>
+      candidate.manifest.tools.some((tool) => tool.name === toolId),
+    );
+    if (!extension) throw new Error(`unknown native tool '${toolId}'`);
+    return extension;
+  }
+}

package/src/runtime/result.ts

@@ -0,0 +1,12 @@
+export interface ToolResult {
+  data: unknown;
+  meta?: Record<string, unknown>;
+}
+
+export interface ExecutionResult {
+  ok: boolean;
+  toolId: string;
+  output?: unknown;
+  meta?: Record<string, unknown>;
+  error?: { code: string; message: string };
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,71 @@
+import type { ExecutionContext, ToolDescriptor, ToolProvider, ToolSearchResult } from "./provider";
+import type { ExecutionResult } from "./result";
+import { executeRuntimeTool, type CreateExecutionContext, type PolicyPreflight } from "./executor";
+import { RuntimeError } from "./errors";
+import { ProviderRegistry } from "./provider-registry";
+import { ToolRegistry } from "./tool-registry";
+
+export interface ToolRuntimeOptions {
+  readonly providers: readonly ToolProvider[];
+  readonly policy: PolicyPreflight;
+  readonly createExecutionContext: CreateExecutionContext;
+}
+
+interface RuntimeState {
+  providers: ProviderRegistry;
+  tools: ToolRegistry;
+  policy: PolicyPreflight;
+  createExecutionContext: CreateExecutionContext;
+}
+
+export class ToolRuntime {
+  constructor(private readonly state: RuntimeState) {}
+
+  search(query: string): Promise<ToolSearchResult[]> {
+    return Promise.resolve(this.state.tools.search(query));
+  }
+
+  describe(toolId: string): Promise<ToolDescriptor> {
+    const descriptor = this.state.tools.get(toolId);
+    if (!descriptor) return Promise.reject(new RuntimeError("TOOL_NOT_FOUND", `unknown tool '${toolId}'`));
+    return Promise.resolve(descriptor);
+  }
+
+  async run(toolId: string, input: unknown): Promise<ExecutionResult> {
+    const descriptor = this.state.tools.get(toolId);
+    if (!descriptor) {
+      return { ok: false, toolId, error: { code: "TOOL_NOT_FOUND", message: `unknown tool '${toolId}'` } };
+    }
+    const provider = this.state.providers.require(descriptor.provider.id);
+    return executeRuntimeTool({
+      descriptor,
+      provider,
+      policy: this.state.policy,
+      createExecutionContext: this.state.createExecutionContext,
+    }, (input ?? {}) as Record<string, unknown>);
+  }
+}
+
+export async function createToolRuntime(options: ToolRuntimeOptions): Promise<ToolRuntime> {
+  const providers = new ProviderRegistry();
+  const tools = new ToolRegistry();
+  for (const provider of options.providers) {
+    providers.register(provider);
+    const descriptors = await provider.listTools();
+    for (const descriptor of descriptors) {
+      if (descriptor.provider.id !== provider.id || descriptor.provider.kind !== provider.kind) {
+        throw new RuntimeError(
+          "PROVIDER_DESCRIPTOR_MISMATCH",
+          `tool '${descriptor.id}' does not identify provider '${provider.id}/${provider.kind}'`,
+        );
+      }
+    }
+    tools.register(descriptors);
+  }
+  return new ToolRuntime({
+    providers,
+    tools,
+    policy: options.policy,
+    createExecutionContext: options.createExecutionContext,
+  });
+}

package/src/runtime/schema.ts

@@ -0,0 +1,49 @@
+import { OmtError } from "./errors";
+
+export type Schema = {
+  type?: string;
+  required?: string[];
+  properties?: Record<string, Schema>;
+  items?: Schema;
+  default?: unknown;
+  maximum?: number;
+  minimum?: number;
+};
+
+function checkType(value: unknown, schema: Schema, path: string): void {
+  const type = schema.type;
+  if (!type || value === undefined) return;
+  let ok = false;
+  switch (type) {
+    case "string": ok = typeof value === "string"; break;
+    case "integer": ok = typeof value === "number" && Number.isInteger(value); break;
+    case "number": ok = typeof value === "number"; break;
+    case "boolean": ok = typeof value === "boolean"; break;
+    case "array":
+      ok = Array.isArray(value);
+      if (ok && schema.items) (value as unknown[]).forEach((item, i) => checkType(item, schema.items!, `${path}[${i}]`));
+      break;
+    case "object": ok = value !== null && typeof value === "object" && !Array.isArray(value); break;
+    default: ok = true;
+  }
+  if (!ok) throw new OmtError("INVALID_INPUT", `'${path}' must be of type ${type}`);
+  if (typeof value === "number") {
+    if (schema.maximum !== undefined && value > schema.maximum) throw new OmtError("INVALID_INPUT", `'${path}' must be <= ${schema.maximum}`);
+    if (schema.minimum !== undefined && value < schema.minimum) throw new OmtError("INVALID_INPUT", `'${path}' must be >= ${schema.minimum}`);
+  }
+}
+
+export function validateInput(schema: Schema | undefined, input: Record<string, unknown>): Record<string, unknown> {
+  if (!schema) return { ...input };
+  const out: Record<string, unknown> = { ...input };
+  const props = schema.properties ?? {};
+  for (const key of Object.keys(props)) {
+    const prop = props[key];
+    if (out[key] === undefined && prop.default !== undefined) out[key] = prop.default;
+  }
+  for (const key of schema.required ?? []) {
+    if (out[key] === undefined || out[key] === null) throw new OmtError("INVALID_INPUT", `missing required field '${key}'`);
+  }
+  for (const key of Object.keys(out)) if (props[key]) checkType(out[key], props[key], key);
+  return out;
+}

package/src/runtime/tool-registry.ts

@@ -0,0 +1,54 @@
+import type { ToolDescriptor, ToolSearchResult } from "./provider";
+import { RuntimeError } from "./errors";
+
+const NAME_WEIGHT = 3;
+const KEYWORD_WEIGHT = 2;
+const DESCRIPTION_WEIGHT = 1;
+
+export class ToolRegistry {
+  private readonly tools = new Map<string, ToolDescriptor>();
+
+  register(descriptors: readonly ToolDescriptor[]): void {
+    const ids = new Set<string>();
+    for (const descriptor of descriptors) {
+      if (this.tools.has(descriptor.id) || ids.has(descriptor.id)) {
+        throw new RuntimeError("DUPLICATE_TOOL_ID", `duplicate tool '${descriptor.id}'`);
+      }
+      ids.add(descriptor.id);
+    }
+    for (const descriptor of descriptors) {
+      this.tools.set(descriptor.id, descriptor);
+    }
+  }
+
+  get(toolId: string): ToolDescriptor | undefined {
+    return this.tools.get(toolId);
+  }
+
+  search(query: string): ToolSearchResult[] {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) return [];
+    return [...this.tools.values()]
+      .map((descriptor) => ({ descriptor, score: this.score(descriptor, tokens) }))
+      .filter((hit) => hit.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .map(({ descriptor }) => {
+        const { inputSchema: _inputSchema, ...summary } = descriptor;
+        return summary;
+      });
+  }
+
+  private score(descriptor: ToolDescriptor, tokens: string[]): number {
+    const id = descriptor.id.toLowerCase();
+    const description = descriptor.description.toLowerCase();
+    const keywords = (descriptor.keywords ?? []).map((keyword) => keyword.toLowerCase());
+    return tokens.reduce((score, token) => {
+      if (id.includes(token)) return score + NAME_WEIGHT;
+      if (keywords.some((keyword) => keyword.includes(token) || token.includes(keyword))) {
+        return score + KEYWORD_WEIGHT;
+      }
+      if (description.includes(token)) return score + DESCRIPTION_WEIGHT;
+      return score;
+    }, 0);
+  }
+}