@cmetech/otto 1.1.1 → 1.2.4

package/packages/coworker-vault/src/data-vault.test.ts

@@ -0,0 +1,199 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AuditLog } from '@otto/coworker-utils';
+import { LocalDataVault } from './data-vault.js';
+import { VaultEntryNotFound, VaultEntryMalformed, BindingRefMalformed } from './errors.js';
+
+function ctx() {
+  const root = mkdtempSync(join(tmpdir(), 'vault-'));
+  return {
+    root,
+    audit: new AuditLog({ path: join(root, 'audit.jsonl') }),
+    globalDir: join(root, 'global'),
+    wsDir: join(root, 'ws'),
+  };
+}
+
+describe('LocalDataVault', () => {
+  it('round-trips an entry through set/get', async () => {
+    const c = ctx();
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    const ref = { engine: 'jira', name: 'prod' };
+    await vault.set(ref, { url: 'u', email: 'e', token: 't' });
+    const entry = await vault.get(ref);
+    assert.equal(entry.engine, 'jira');
+    assert.equal(entry.name, 'prod');
+    assert.equal(entry.fields.url, 'u');
+    assert.equal(entry.fields.email, 'e');
+    assert.equal(entry.fields.token, 't');
+    assert.ok(entry.created_at, 'expected created_at to be truthy');
+  });
+
+  it('stores files with mode 0600', async () => {
+    const c = ctx();
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    await vault.set({ engine: 'jira', name: 'prod' }, { url: 'u', email: 'e', token: 't' });
+    const path = join(c.globalDir, 'data_vault', 'jira-prod.json');
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600);
+  });
+
+  it('throws VaultEntryNotFound when entry missing', async () => {
+    const c = ctx();
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    await assert.rejects(
+      vault.get({ engine: 'jira', name: 'missing' }),
+      (err: Error) => err instanceof VaultEntryNotFound,
+    );
+  });
+
+  it('throws VaultEntryMalformed when file is invalid JSON', async () => {
+    const c = ctx();
+    const dir = join(c.globalDir, 'data_vault');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'jira-prod.json'), 'not json');
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    await assert.rejects(
+      vault.get({ engine: 'jira', name: 'prod' }),
+      (err: Error) => err instanceof VaultEntryMalformed,
+    );
+  });
+
+  it('atomic write does not leave torn files; orphan .tmp cleaned on next open', async () => {
+    const c = ctx();
+    const dir = join(c.globalDir, 'data_vault');
+    mkdirSync(dir, { recursive: true });
+    const orphan = join(dir, 'jira-orphan.json.tmp');
+    writeFileSync(orphan, '{"partial":');
+    assert.ok(existsSync(orphan), 'precondition: orphan exists');
+    new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    assert.equal(existsSync(orphan), false, 'orphan .tmp should be swept');
+  });
+
+  it('remove deletes the entry file and emits audit', async () => {
+    const c = ctx();
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    const ref = { engine: 'jira', name: 'prod' };
+    await vault.set(ref, { url: 'u', email: 'e', token: 't' });
+    const path = join(c.globalDir, 'data_vault', 'jira-prod.json');
+    assert.ok(existsSync(path), 'precondition: file exists after set');
+    await vault.remove(ref);
+    assert.equal(existsSync(path), false, 'file should no longer exist after remove');
+  });
+
+  it('list returns entries with engine, name, scope, fields_set, last_modified', async () => {
+    const c = ctx();
+    const vault = new LocalDataVault({ globalDir: c.globalDir, audit: c.audit });
+    await vault.set({ engine: 'jira', name: 'prod' }, { url: 'u', email: 'e', token: 't' });
+    await vault.set({ engine: 'jira', name: 'test' }, { url: 'u2' });
+    const entries = await vault.list();
+    assert.equal(entries.length, 2);
+    const prod = entries.find((e) => e.name === 'prod');
+    const test = entries.find((e) => e.name === 'test');
+    assert.ok(prod);
+    assert.ok(test);
+    assert.equal(prod!.engine, 'jira');
+    assert.equal(prod!.scope, 'global');
+    assert.deepEqual(prod!.fields_set.sort(), ['email', 'token', 'url']);
+    assert.ok(prod!.last_modified_at);
+    assert.deepEqual(test!.fields_set, ['url']);
+  });
+
+  it('parseRef parses jira:prod into { engine, name }', () => {
+    const ref = LocalDataVault.parseRef('jira:prod');
+    assert.deepEqual(ref, { engine: 'jira', name: 'prod' });
+  });
+
+  it('parseRef throws BindingRefMalformed on bad input', () => {
+    assert.throws(
+      () => LocalDataVault.parseRef('jira/prod'),
+      (err: Error) => err instanceof BindingRefMalformed,
+    );
+    assert.throws(
+      () => LocalDataVault.parseRef(''),
+      (err: Error) => err instanceof BindingRefMalformed,
+    );
+  });
+});
+
+describe('LocalDataVault — workspace + sidecar', () => {
+  it('resolves workspace entry over global', async () => {
+    const c = ctx();
+    mkdirSync(join(c.wsDir, 'data_vault'), { recursive: true });
+    const v = new LocalDataVault({ globalDir: c.globalDir, workspaceDir: c.wsDir, audit: c.audit });
+    await v.set({ engine: 'jira', name: 'prod' }, { url: 'global' });
+    mkdirSync(join(c.globalDir, 'data_vault'), { recursive: true });
+    writeFileSync(
+      join(c.globalDir, 'data_vault', 'jira-prod.json'),
+      JSON.stringify(
+        {
+          _schema: 1,
+          engine: 'jira',
+          name: 'prod',
+          fields: { url: 'g' },
+          created_at: '2026-06-01T00:00:00.000Z',
+          last_modified_at: '2026-06-01T00:00:00.000Z',
+        },
+        null,
+        2,
+      ),
+      { mode: 0o600 },
+    );
+    const got = await v.get({ engine: 'jira', name: 'prod' });
+    assert.equal(got.fields.url, 'global');
+  });
+
+  it('falls back to global when workspace entry absent', async () => {
+    const c = ctx();
+    mkdirSync(c.wsDir, { recursive: true });
+    const v = new LocalDataVault({ globalDir: c.globalDir, workspaceDir: c.wsDir, audit: c.audit });
+    mkdirSync(join(c.globalDir, 'data_vault'), { recursive: true });
+    writeFileSync(
+      join(c.globalDir, 'data_vault', 'jira-prod.json'),
+      JSON.stringify(
+        {
+          _schema: 1,
+          engine: 'jira',
+          name: 'prod',
+          fields: { url: 'g' },
+          created_at: '2026-06-01T00:00:00.000Z',
+          last_modified_at: '2026-06-01T00:00:00.000Z',
+        },
+        null,
+        2,
+      ),
+      { mode: 0o600 },
+    );
+    const got = await v.get({ engine: 'jira', name: 'prod' });
+    assert.equal(got.fields.url, 'g');
+  });
+
+  it('updates _last_modified.json on set; lookupLastModified reads it', async () => {
+    const c = ctx();
+    const v = new LocalDataVault({ globalDir: c.globalDir, workspaceDir: undefined, audit: c.audit });
+    await v.set({ engine: 'jira', name: 'prod' }, { url: 'u' });
+    const sidecarPath = join(c.globalDir, 'data_vault', '_last_modified.json');
+    assert.ok(existsSync(sidecarPath));
+    const data = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+    assert.ok(data['jira:prod']);
+    const ts = await v.lookupLastModified('jira:prod');
+    assert.equal(ts, data['jira:prod']);
+  });
+
+  it('lookupLastModified returns null for missing entries', async () => {
+    const c = ctx();
+    const v = new LocalDataVault({ globalDir: c.globalDir, workspaceDir: undefined, audit: c.audit });
+    assert.equal(await v.lookupLastModified('jira:missing'), null);
+  });
+
+  it('remove updates sidecar (key dropped)', async () => {
+    const c = ctx();
+    const v = new LocalDataVault({ globalDir: c.globalDir, workspaceDir: undefined, audit: c.audit });
+    await v.set({ engine: 'jira', name: 'prod' }, { url: 'u' });
+    await v.remove({ engine: 'jira', name: 'prod' });
+    assert.equal(await v.lookupLastModified('jira:prod'), null);
+  });
+});

package/packages/coworker-vault/src/data-vault.ts

@@ -0,0 +1,257 @@
+// packages/coworker-vault/src/data-vault.ts
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { AuditLog, type AuditRecord } from '@otto/coworker-utils';
+import type { EntryRef, VaultEntry, VaultScope } from './types.js';
+import { BindingRefMalformed, VaultEntryMalformed, VaultEntryNotFound } from './errors.js';
+
+export interface LocalDataVaultOptions {
+  globalDir: string;
+  workspaceDir?: string;
+  audit: AuditLog;
+  now?: () => string;
+}
+
+export interface ListedEntry {
+  engine: string;
+  name: string;
+  scope: VaultScope;
+  fields_set: string[];
+  last_modified_at: string;
+}
+
+const REF_RE = /^([a-z][a-z0-9-]*):([a-z][a-z0-9-]*)$/;
+
+export class LocalDataVault {
+  private readonly globalRoot: string;
+  private readonly workspaceRoot?: string;
+  private readonly audit: AuditLog;
+  private readonly now: () => string;
+
+  constructor(opts: LocalDataVaultOptions) {
+    this.globalRoot = opts.globalDir;
+    this.workspaceRoot = opts.workspaceDir;
+    this.audit = opts.audit;
+    this.now = opts.now ?? (() => new Date().toISOString());
+    this.sweepOrphans(this.globalVaultDir());
+    const ws = this.workspaceVaultDir();
+    if (ws) this.sweepOrphans(ws);
+  }
+
+  static parseRef(input: string): EntryRef {
+    const m = REF_RE.exec(input);
+    if (!m) throw new BindingRefMalformed(input);
+    return { engine: m[1]!, name: m[2]! };
+  }
+
+  static formatRef(ref: EntryRef): string {
+    return `${ref.engine}:${ref.name}`;
+  }
+
+  private globalVaultDir(): string {
+    return join(this.globalRoot, 'data_vault');
+  }
+
+  private workspaceVaultDir(): string | undefined {
+    return this.workspaceRoot ? join(this.workspaceRoot, 'data_vault') : undefined;
+  }
+
+  private fileNameFor(ref: EntryRef): string {
+    return `${ref.engine}-${ref.name}.json`;
+  }
+
+  private resolveScope(ref: EntryRef): { dir: string; scope: VaultScope } | null {
+    const ws = this.workspaceVaultDir();
+    if (ws && existsSync(join(ws, this.fileNameFor(ref)))) {
+      return { dir: ws, scope: 'workspace' };
+    }
+    if (existsSync(join(this.globalVaultDir(), this.fileNameFor(ref)))) {
+      return { dir: this.globalVaultDir(), scope: 'global' };
+    }
+    return null;
+  }
+
+  private writeScope(forceWorkspace: boolean): { dir: string; scope: VaultScope } {
+    if (forceWorkspace) {
+      const ws = this.workspaceVaultDir();
+      if (!ws) throw new Error('Workspace scope requested but no workspace root configured.');
+      return { dir: ws, scope: 'workspace' };
+    }
+    const ws = this.workspaceVaultDir();
+    if (ws && existsSync(ws)) return { dir: ws, scope: 'workspace' };
+    return { dir: this.globalVaultDir(), scope: 'global' };
+  }
+
+  async set(
+    ref: EntryRef,
+    fields: Record<string, string>,
+    opts: { forceWorkspace?: boolean } = {},
+  ): Promise<void> {
+    const target = this.writeScope(opts.forceWorkspace ?? false);
+    mkdirSync(target.dir, { recursive: true, mode: 0o700 });
+    const path = join(target.dir, this.fileNameFor(ref));
+    const tmp = `${path}.tmp`;
+    const existing = existsSync(path) ? this.readEntry(path) : null;
+    const ts = this.now();
+    const entry: VaultEntry = {
+      _schema: 1,
+      engine: ref.engine,
+      name: ref.name,
+      fields,
+      created_at: existing?.created_at ?? ts,
+      last_modified_at: ts,
+    };
+    writeFileSync(tmp, JSON.stringify(entry, null, 2), { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    this.audit.append({
+      _schema: 1,
+      ts,
+      producer: 'vault',
+      action: 'set',
+      detail: {
+        engine: ref.engine,
+        name: ref.name,
+        scope: target.scope,
+        fields_set: Object.keys(fields),
+      },
+    } satisfies AuditRecord);
+    this.writeSidecar(target.scope, (m) => {
+      m[LocalDataVault.formatRef(ref)] = ts;
+    });
+  }
+
+  async get(ref: EntryRef): Promise<VaultEntry> {
+    const r = this.resolveScope(ref);
+    if (!r) {
+      const searched: string[] = [];
+      const ws = this.workspaceVaultDir();
+      if (ws) searched.push(join(ws, this.fileNameFor(ref)));
+      searched.push(join(this.globalVaultDir(), this.fileNameFor(ref)));
+      throw new VaultEntryNotFound(ref.engine, ref.name, searched);
+    }
+    const entry = this.readEntry(join(r.dir, this.fileNameFor(ref)));
+    this.audit.append({
+      _schema: 1,
+      ts: this.now(),
+      producer: 'vault',
+      action: 'get',
+      detail: { engine: ref.engine, name: ref.name, scope_resolved: r.scope },
+    });
+    return entry;
+  }
+
+  async remove(ref: EntryRef): Promise<void> {
+    const r = this.resolveScope(ref);
+    if (!r) throw new VaultEntryNotFound(ref.engine, ref.name, []);
+    unlinkSync(join(r.dir, this.fileNameFor(ref)));
+    this.audit.append({
+      _schema: 1,
+      ts: this.now(),
+      producer: 'vault',
+      action: 'remove',
+      detail: { engine: ref.engine, name: ref.name, scope: r.scope },
+    });
+    this.writeSidecar(r.scope, (m) => {
+      delete m[LocalDataVault.formatRef(ref)];
+    });
+  }
+
+  async lookupLastModified(refStr: string): Promise<string | null> {
+    const ref = LocalDataVault.parseRef(refStr);
+    const r = this.resolveScope(ref);
+    if (!r) return null;
+    const sidecar = this.readSidecar(this.sidecarPathFor(r.scope));
+    return sidecar[refStr] ?? null;
+  }
+
+  private sidecarPathFor(scope: VaultScope): string {
+    const dir = scope === 'workspace' ? this.workspaceVaultDir()! : this.globalVaultDir();
+    return join(dir, '_last_modified.json');
+  }
+
+  private readSidecar(path: string): Record<string, string> {
+    if (!existsSync(path)) return {};
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as Record<string, string>;
+    } catch {
+      return {};
+    }
+  }
+
+  private writeSidecar(scope: VaultScope, mutate: (m: Record<string, string>) => void): void {
+    const path = this.sidecarPathFor(scope);
+    const data = this.readSidecar(path);
+    mutate(data);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+  }
+
+  async list(): Promise<ListedEntry[]> {
+    const out: ListedEntry[] = [];
+    const collect = (dir: string | undefined, scope: VaultScope) => {
+      if (!dir || !existsSync(dir)) return;
+      for (const f of readdirSync(dir)) {
+        if (!f.endsWith('.json') || f.startsWith('_')) continue;
+        try {
+          const entry = this.readEntry(join(dir, f));
+          out.push({
+            engine: entry.engine,
+            name: entry.name,
+            scope,
+            fields_set: Object.keys(entry.fields),
+            last_modified_at: entry.last_modified_at,
+          });
+        } catch {
+          /* skip malformed */
+        }
+      }
+    };
+    collect(this.workspaceVaultDir(), 'workspace');
+    collect(this.globalVaultDir(), 'global');
+    return out;
+  }
+
+  private readEntry(path: string): VaultEntry {
+    let raw: string;
+    try {
+      raw = readFileSync(path, 'utf8');
+    } catch (err) {
+      throw new VaultEntryMalformed(path, (err as Error).message);
+    }
+    let json: unknown;
+    try {
+      json = JSON.parse(raw);
+    } catch (err) {
+      throw new VaultEntryMalformed(path, `JSON parse: ${(err as Error).message}`);
+    }
+    if (!json || typeof json !== 'object' || (json as { _schema?: unknown })._schema !== 1) {
+      throw new VaultEntryMalformed(path, 'unexpected _schema');
+    }
+    return json as VaultEntry;
+  }
+
+  private sweepOrphans(dir: string): void {
+    if (!existsSync(dir)) return;
+    for (const f of readdirSync(dir)) {
+      if (f.endsWith('.json.tmp')) {
+        try {
+          unlinkSync(join(dir, f));
+        } catch {
+          /* best effort */
+        }
+      }
+    }
+  }
+}

package/packages/coworker-vault/src/engine-registry.test.ts

@@ -0,0 +1,120 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { EngineRegistry } from './engine-registry.js';
+import { EngineNotFound } from './errors.js';
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), 'engines-'));
+}
+
+describe('EngineRegistry', () => {
+  it('loads the bundled JIRA seed by id', async () => {
+    const reg = await EngineRegistry.load({ userDir: tmp(), workspaceDir: undefined });
+    const jira = reg.get('jira');
+    assert.ok(jira, 'expected bundled jira engine to be loaded');
+    assert.equal(jira!.id, 'jira');
+    assert.deepEqual(jira!.fields.map((f) => f.name), ['url', 'email', 'token']);
+    const token = jira!.fields.find((f) => f.name === 'token');
+    assert.ok(token);
+    assert.equal(token!.secret, true);
+  });
+
+  it('throws EngineNotFound on unknown id', async () => {
+    const reg = await EngineRegistry.load({ userDir: tmp(), workspaceDir: undefined });
+    assert.throws(
+      () => reg.require('servicenow'),
+      (err: Error) => err.name === 'EngineNotFound' && err instanceof EngineNotFound,
+    );
+  });
+
+  it('workspace YAML overrides user YAML overrides builtin', async () => {
+    const userDir = tmp();
+    const wsDir = tmp();
+    writeFileSync(
+      join(userDir, 'jira.yaml'),
+      `schema_version: 1
+id: jira
+label: "Jira (user)"
+fields:
+  - name: url
+    label: URL
+    secret: false
+    required: true
+`,
+    );
+    writeFileSync(
+      join(wsDir, 'jira.yaml'),
+      `schema_version: 1
+id: jira
+label: "Jira (workspace)"
+fields:
+  - name: url
+    label: URL
+    secret: false
+    required: true
+`,
+    );
+    const reg = await EngineRegistry.load({ userDir, workspaceDir: wsDir });
+    assert.equal(reg.get('jira')!.label, 'Jira (workspace)');
+  });
+
+  it('accepts unknown top-level keys (forward compat with test: block)', async () => {
+    const userDir = tmp();
+    writeFileSync(
+      join(userDir, 'future.yaml'),
+      `schema_version: 1
+id: future
+label: Future Engine
+fields:
+  - name: token
+    label: Token
+    secret: true
+    required: true
+test:
+  endpoint: /api/v1/ping
+  expected_status: 200
+`,
+    );
+    const reg = await EngineRegistry.load({ userDir, workspaceDir: undefined });
+    const engine = reg.get('future');
+    assert.ok(engine);
+    assert.equal(engine!.id, 'future');
+  });
+
+  it('skips engines with malformed YAML and continues loading others', async () => {
+    const userDir = tmp();
+    // Missing id, empty fields — schema invalid
+    writeFileSync(
+      join(userDir, 'broken.yaml'),
+      `schema_version: 1
+label: Broken
+fields: []
+`,
+    );
+    const reg = await EngineRegistry.load({ userDir, workspaceDir: undefined });
+    assert.equal(reg.get('broken'), undefined);
+    // Builtin jira should still load
+    assert.ok(reg.get('jira'), 'builtin jira should still load despite broken user file');
+  });
+
+  it('field name must match /^[a-z][a-z0-9_]*$/', async () => {
+    const userDir = tmp();
+    writeFileSync(
+      join(userDir, 'bad.yaml'),
+      `schema_version: 1
+id: bad
+label: Bad
+fields:
+  - name: Bad-Name
+    label: Bad Name
+    secret: false
+    required: true
+`,
+    );
+    const reg = await EngineRegistry.load({ userDir, workspaceDir: undefined });
+    assert.equal(reg.get('bad'), undefined);
+  });
+});

package/packages/coworker-vault/src/engine-registry.ts

@@ -0,0 +1,107 @@
+// packages/coworker-vault/src/engine-registry.ts
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { parse as parseYaml } from 'yaml';
+import type { EngineDefinition, EngineSource } from './types.js';
+import { EngineNotFound } from './errors.js';
+
+const ENGINE_FIELD_SCHEMA = z.object({
+  name: z.string().regex(/^[a-z][a-z0-9_]*$/, 'name must match /^[a-z][a-z0-9_]*$/'),
+  label: z.string().min(1),
+  secret: z.boolean(),
+  required: z.boolean(),
+  default: z.string().optional(),
+});
+
+const ENGINE_SCHEMA = z
+  .object({
+    schema_version: z.literal(1),
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/, 'id must match /^[a-z][a-z0-9-]*$/'),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    fields: z.array(ENGINE_FIELD_SCHEMA).min(1),
+  })
+  .passthrough(); // accept unknown top-level keys (forward compat for test: blocks etc.)
+
+function builtinDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), 'engines');
+}
+
+export interface RegistryResolution {
+  engine: EngineDefinition;
+  source: EngineSource;
+}
+
+export interface LoadOptions {
+  userDir?: string | undefined;
+  workspaceDir?: string | undefined;
+}
+
+export class EngineRegistry {
+  private constructor(private readonly resolutions: Map<string, RegistryResolution>) {}
+
+  static async load(opts: LoadOptions = {}): Promise<EngineRegistry> {
+    const map = new Map<string, RegistryResolution>();
+    EngineRegistry.loadDir(builtinDir(), 'builtin', map);
+    if (opts.userDir && existsSync(opts.userDir)) {
+      EngineRegistry.loadDir(opts.userDir, 'user', map);
+    }
+    if (opts.workspaceDir && existsSync(opts.workspaceDir)) {
+      EngineRegistry.loadDir(opts.workspaceDir, 'workspace', map);
+    }
+    return new EngineRegistry(map);
+  }
+
+  private static loadDir(dir: string, source: EngineSource, out: Map<string, RegistryResolution>): void {
+    if (!existsSync(dir)) return;
+    let entries: string[] = [];
+    try {
+      entries = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+    } catch {
+      return;
+    }
+    for (const f of entries) {
+      const path = join(dir, f);
+      let parsed: unknown;
+      try {
+        parsed = parseYaml(readFileSync(path, 'utf8'));
+      } catch (err) {
+        process.stderr.write(
+          `engine-registry: parse failed ${path}: ${(err as Error).message}\n`,
+        );
+        continue;
+      }
+      const result = ENGINE_SCHEMA.safeParse(parsed);
+      if (!result.success) {
+        const detail = result.error.issues
+          .map((i) => `${i.path.join('.')}: ${i.message}`)
+          .join('; ');
+        process.stderr.write(`engine-registry: schema invalid ${path}: ${detail}\n`);
+        continue;
+      }
+      out.set(result.data.id, { engine: result.data as EngineDefinition, source });
+    }
+  }
+
+  get(id: string): EngineDefinition | undefined {
+    return this.resolutions.get(id)?.engine;
+  }
+
+  require(id: string): EngineDefinition {
+    const r = this.resolutions.get(id);
+    if (!r) throw new EngineNotFound(id);
+    return r.engine;
+  }
+
+  source(id: string): EngineSource | undefined {
+    return this.resolutions.get(id)?.source;
+  }
+
+  all(): RegistryResolution[] {
+    return [...this.resolutions.values()];
+  }
+}
+
+export { ENGINE_SCHEMA };

package/packages/coworker-vault/src/engines/jira.yaml

@@ -0,0 +1,17 @@
+schema_version: 1
+id: jira
+label: Jira
+description: Atlassian Jira Cloud / Server via Basic auth (email + API token)
+fields:
+  - name: url
+    label: "Instance URL (e.g. https://yourorg.atlassian.net)"
+    secret: false
+    required: true
+  - name: email
+    label: "Atlassian account email"
+    secret: false
+    required: true
+  - name: token
+    label: "API token (from id.atlassian.com → Account → Security)"
+    secret: true
+    required: true