@chozzz/vargos 3.1.4 → 3.2.1

package/dist/core/bus.js

@@ -0,0 +1,133 @@
+/**
+ * The Bus — the single owner of the method registry and the only wrapper for all
+ * services. `register`/`unregister`/`call`/`emit`/`on` and the registry projection
+ * consumed by all three surfaces (CLI, agent tools, JSON-RPC) live here.
+ *
+ * Two distinct concepts, deliberately not conflated:
+ *   - Methods (registry): register / call. Validated by zod. Surfaced everywhere.
+ *   - Events (pub/sub): emit / on. Unvalidated broadcast. emit with no listeners
+ *     is a silent no-op.
+ */
+import EventEmitter from 'node:events';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { MethodNotFoundError, ValidationError } from './errors.js';
+export class EmitterBus {
+    registry = new Map();
+    ee = new EventEmitter();
+    wiring = new Map();
+    /** Set by the loader around a service's init() so register/on attribute correctly. */
+    loadingService = null;
+    constructor() {
+        this.ee.setMaxListeners(0); // a long-lived server has many legitimate listeners
+        this.registerIntrospection();
+    }
+    // ── Loader hook ────────────────────────────────────────────────────────────────
+    // The loader brackets a service's (async) init() with beginLoading/endLoading so
+    // every register()/on() it does is attributed to that service. Services never load
+    // concurrently, so loadingService stays correct across awaits inside init().
+    beginLoading(service) {
+        this.loadingService = service;
+        if (!this.wiring.has(service))
+            this.wiring.set(service, { methods: new Set(), offs: [] });
+    }
+    endLoading() {
+        this.loadingService = null;
+    }
+    /** Release everything the bus wired for a service (methods + event listeners). */
+    releaseService(service) {
+        const w = this.wiring.get(service);
+        if (!w)
+            return;
+        for (const off of w.offs)
+            off();
+        for (const name of w.methods)
+            this.registry.delete(name);
+        this.wiring.delete(service);
+    }
+    // ── Registry ────────────────────────────────────────────────────────────────────
+    register(name, opts, handler) {
+        if (this.registry.has(name)) {
+            throw new Error(`Method already registered: ${name}`);
+        }
+        const service = this.loadingService ?? name.split('.')[0];
+        this.registry.set(name, { name, service, handler, ...opts, internal: opts.internal ?? false });
+        this.wiring.get(service)?.methods.add(name);
+        return () => this.unregister(name);
+    }
+    unregister(name) {
+        const entry = this.registry.get(name);
+        if (!entry)
+            return false;
+        this.registry.delete(name);
+        this.wiring.get(entry.service)?.methods.delete(name);
+        return true;
+    }
+    has(name) {
+        return this.registry.has(name);
+    }
+    async call(name, params) {
+        const entry = this.registry.get(name);
+        if (!entry)
+            throw new MethodNotFoundError(name);
+        const parsed = entry.schema.safeParse(params ?? {});
+        if (!parsed.success)
+            throw new ValidationError(name, parsed.error);
+        return await entry.handler(parsed.data);
+    }
+    list(service) {
+        const out = [];
+        for (const e of this.registry.values()) {
+            if (service && e.service !== service)
+                continue;
+            out.push({
+                name: e.name,
+                service: e.service,
+                description: e.description,
+                cli: e.cli,
+                internal: e.internal ?? false,
+                schema: toJsonSchema(e.schema),
+            });
+        }
+        return out;
+    }
+    // ── Events (pub/sub) ──────────────────────────────────────────────────────────
+    emit(event, payload) {
+        this.ee.emit(event, payload); // no listeners → no-op
+    }
+    on(event, handler) {
+        const fn = handler;
+        this.ee.on(event, fn);
+        const off = () => this.ee.off(event, fn);
+        if (this.loadingService)
+            this.wiring.get(this.loadingService)?.offs.push(off);
+        return off;
+    }
+    // ── Built-in introspection (the registry describing itself) ─────────────────────
+    registerIntrospection() {
+        this.beginLoading('bus');
+        this.register('bus.list', {
+            description: 'List registered methods, optionally scoped to one service. Source of truth for all three surfaces.',
+            schema: z.object({ service: z.string().optional() }),
+            cli: { positional: ['service'] },
+            internal: true,
+        }, (p) => this.list(p.service));
+        this.register('bus.has', {
+            description: 'Check whether a method is registered.',
+            schema: z.object({ method: z.string() }),
+            cli: { positional: ['method'] },
+            internal: true,
+        }, (p) => ({ registered: this.has(p.method) }));
+        this.endLoading();
+    }
+}
+/** Convert a zod schema to JSON Schema, swallowing conversion failures. */
+function toJsonSchema(schema) {
+    try {
+        return zodToJsonSchema(schema);
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=bus.js.map

package/dist/core/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../core/bus.ts"],"names":[],"mappings":"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"}

package/dist/core/cli.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI projection (surface 1). Pure helpers that turn the registry (MethodInfo[])
+ * into listings, --help text, and a params object — plus a minimal JSON-RPC client
+ * for proxying to a running daemon. Nothing here is hand-written per command; it all
+ * derives from the registry.
+ */
+import type { MethodInfo } from './types.js';
+export interface ParsedCli {
+    service?: string;
+    method?: string;
+    args: string[];
+    help: boolean;
+}
+/** Parse `vargos <service> [method] [args...] [--help]`. Returns reserved=true for built-in commands. */
+export declare function parseCli(argv: string[]): ParsedCli & {
+    reserved: boolean;
+};
+/**
+ * Build a params object from CLI args using the method's cli.positional order and
+ * schema. Positionals map 1:1 to keys; `--flag value` and bare `--flag` (boolean)
+ * are named overrides. Too many positionals → usage error (caller catches).
+ * Missing required fields are left out so zod reports them identically on all surfaces.
+ */
+export declare function buildParams(info: MethodInfo, args: string[]): Record<string, unknown>;
+/** `vargos <service>` — list that service's method names. */
+export declare function renderList(service: string, infos: MethodInfo[]): string;
+/** `vargos <service> --help` — usage line, wrapped description, and options per method. */
+export declare function renderHelp(service: string, infos: MethodInfo[]): string;
+export declare class RpcClient {
+    private readonly host;
+    private readonly port;
+    constructor(host: string, port: number);
+    /** One request/response over a fresh connection. Rejects on connect failure. */
+    call<T = unknown>(method: string, params?: unknown, connectTimeoutMs?: number): Promise<T>;
+    /** Is a daemon answering on the port? */
+    isUp(): Promise<boolean>;
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/core/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../core/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAID,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAW1E;AAiBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BrF;AA2CD,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAKvE;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAavE;AAID,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAU,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAnC,IAAI,EAAE,MAAM,EAAmB,IAAI,EAAE,MAAM;IAExE,gFAAgF;IAChF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,gBAAgB,SAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BxF,yCAAyC;IACnC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAQ/B"}

package/dist/core/cli.js

@@ -0,0 +1,199 @@
+/**
+ * CLI projection (surface 1). Pure helpers that turn the registry (MethodInfo[])
+ * into listings, --help text, and a params object — plus a minimal JSON-RPC client
+ * for proxying to a running daemon. Nothing here is hand-written per command; it all
+ * derives from the registry.
+ */
+import { createConnection } from 'node:net';
+const RESERVED = new Set(['start', 'onboard', 'chat', 'sync', 'migrate', '--help', '-h', '--version', '-v']);
+/** Parse `vargos <service> [method] [args...] [--help]`. Returns reserved=true for built-in commands. */
+export function parseCli(argv) {
+    const help = argv.includes('--help') || argv.includes('-h');
+    const rest = argv.filter(a => a !== '--help' && a !== '-h');
+    const service = rest[0];
+    return {
+        reserved: !!service && RESERVED.has(service),
+        service,
+        method: rest[1],
+        args: rest.slice(2),
+        help,
+    };
+}
+function coerce(prop, value) {
+    if (typeof value === 'boolean')
+        return value;
+    const t = prop?.type;
+    if (t === 'number' || t === 'integer') {
+        const n = Number(value);
+        return Number.isNaN(n) ? value : n;
+    }
+    if (t === 'boolean')
+        return value === 'true';
+    return value;
+}
+/**
+ * Build a params object from CLI args using the method's cli.positional order and
+ * schema. Positionals map 1:1 to keys; `--flag value` and bare `--flag` (boolean)
+ * are named overrides. Too many positionals → usage error (caller catches).
+ * Missing required fields are left out so zod reports them identically on all surfaces.
+ */
+export function buildParams(info, args) {
+    const schema = (info.schema ?? {});
+    const props = schema.properties ?? {};
+    const positionalKeys = info.cli?.positional ?? [];
+    const positionals = [];
+    const named = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                named[key] = true;
+            }
+            else {
+                named[key] = next;
+                i++;
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    if (positionals.length > positionalKeys.length) {
+        const shape = positionalKeys.length ? positionalKeys.map(k => `<${k}>`).join(' ') : '(named flags only)';
+        throw new Error(`too many arguments for ${info.name}. Usage: ${info.service} ${info.name.split('.').slice(1).join('.')} ${shape}`);
+    }
+    const out = {};
+    positionalKeys.forEach((key, idx) => {
+        if (positionals[idx] !== undefined)
+            out[key] = coerce(props[key], positionals[idx]);
+    });
+    for (const [k, v] of Object.entries(named))
+        out[k] = coerce(props[k], v);
+    return out;
+}
+// ─── rendering ───────────────────────────────────────────────────────────────────
+function shortMethod(info) {
+    return info.name.includes('.') ? info.name.split('.').slice(1).join('.') : info.name;
+}
+/** Positional args in cli.positional order: `<key>` required, `[<key>]` optional. */
+function positionalUsage(info) {
+    const required = new Set((info.schema ?? {}).required ?? []);
+    return (info.cli?.positional ?? [])
+        .map(k => (required.has(k) ? `<${k}>` : `[<${k}>]`))
+        .join(' ');
+}
+/** Named flags (schema keys not consumed positionally): `--k <type>` / `[--k]` etc. */
+function namedFlags(info) {
+    const schema = (info.schema ?? {});
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const positional = new Set(info.cli?.positional ?? []);
+    const out = [];
+    for (const [key, p] of Object.entries(props)) {
+        if (positional.has(key))
+            continue;
+        const token = p.type === 'boolean' ? `--${key}` : `--${key} <${p.type ?? 'value'}>`;
+        out.push(required.has(key) ? token : `[${token}]`);
+    }
+    return out;
+}
+/** Word-wrap to `width`, continuation lines prefixed with `indent`. */
+function wrap(text, width, indent) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line && (line + ' ' + word).length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.join('\n' + indent);
+}
+/** `vargos <service>` — list that service's method names. */
+export function renderList(service, infos) {
+    if (infos.length === 0)
+        return `No methods registered for "${service}".`;
+    const width = Math.max(...infos.map(i => shortMethod(i).length));
+    const lines = infos.map(i => `  ${service} ${shortMethod(i).padEnd(width)}  ${i.description.split('. ')[0]}`);
+    return `${service} — ${infos.length} method${infos.length === 1 ? '' : 's'}\n\n${lines.join('\n')}`;
+}
+/** `vargos <service> --help` — usage line, wrapped description, and options per method. */
+export function renderHelp(service, infos) {
+    if (infos.length === 0)
+        return `No methods registered for "${service}".`;
+    const DESC = '      ';
+    const OPTS = '      options: ';
+    const blocks = infos.map(i => {
+        const pos = positionalUsage(i);
+        const out = [`  ${service} ${shortMethod(i)}${pos ? ' ' + pos : ''}`];
+        out.push(`${DESC}${wrap(i.description, 72, DESC)}`);
+        const flags = namedFlags(i);
+        if (flags.length)
+            out.push(`${OPTS}${wrap(flags.join(' '), 64, ' '.repeat(OPTS.length))}`);
+        return out.join('\n');
+    });
+    return `${service} — ${infos.length} method${infos.length === 1 ? '' : 's'}\n\n${blocks.join('\n\n')}`;
+}
+// ─── JSON-RPC client ─────────────────────────────────────────────────────────────
+export class RpcClient {
+    host;
+    port;
+    constructor(host, port) {
+        this.host = host;
+        this.port = port;
+    }
+    /** One request/response over a fresh connection. Rejects on connect failure. */
+    call(method, params, connectTimeoutMs = 2000) {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ host: this.host, port: this.port });
+            let buffer = '';
+            let settled = false;
+            const fail = (err) => { if (!settled) {
+                settled = true;
+                socket.destroy();
+                reject(err);
+            } };
+            socket.setTimeout(connectTimeoutMs, () => fail(new Error('daemon connect timeout')));
+            socket.on('connect', () => {
+                socket.setTimeout(0); // no idle limit once connected; long calls (agent) are allowed
+                socket.write(JSON.stringify({ jsonrpc: '2.0', method, params, id: 1 }) + '\n');
+            });
+            socket.on('error', (err) => fail(err));
+            socket.on('data', (chunk) => {
+                buffer += chunk.toString();
+                const nl = buffer.indexOf('\n');
+                if (nl === -1)
+                    return;
+                settled = true;
+                socket.end();
+                try {
+                    const res = JSON.parse(buffer.slice(0, nl));
+                    if (res.error)
+                        reject(new Error(res.error.message ?? 'rpc error'));
+                    else
+                        resolve(res.result);
+                }
+                catch (err) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+        });
+    }
+    /** Is a daemon answering on the port? */
+    async isUp() {
+        try {
+            await this.call('bus.has', { method: 'bus.list' }, 1000);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/core/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../core/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structured bus errors. JSON-RPC error codes are attached so the RPC surface can
+ * map them without re-classifying — every surface (CLI, RPC, agent) surfaces the
+ * same error for the same cause.
+ */
+import type { z } from 'zod';
+/** Format a zod error's issues as `path: message` entries joined by `; `. */
+export declare function formatZodIssues(error: z.ZodError): string;
+export declare class BusError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/** `bus.call('does.not.exist')` — method is not in the registry. */
+export declare class MethodNotFoundError extends BusError {
+    constructor(method: string);
+}
+/** Params failed the method's zod schema. Carries the formatted issue list. */
+export declare class ValidationError extends BusError {
+    constructor(method: string, error: z.ZodError);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../core/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAEzD;AAED,qBAAa,QAAS,SAAQ,KAAK;IACJ,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAtC,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM;CAInD;AAED,oEAAoE;AACpE,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,MAAM,EAAE,MAAM;CAG3B;AAED,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ;CAG9C"}

package/dist/core/errors.js

@@ -0,0 +1,30 @@
+/**
+ * Structured bus errors. JSON-RPC error codes are attached so the RPC surface can
+ * map them without re-classifying — every surface (CLI, RPC, agent) surfaces the
+ * same error for the same cause.
+ */
+/** Format a zod error's issues as `path: message` entries joined by `; `. */
+export function formatZodIssues(error) {
+    return error.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+}
+export class BusError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+/** `bus.call('does.not.exist')` — method is not in the registry. */
+export class MethodNotFoundError extends BusError {
+    constructor(method) {
+        super(`Method not found: ${method}`, -32601);
+    }
+}
+/** Params failed the method's zod schema. Carries the formatted issue list. */
+export class ValidationError extends BusError {
+    constructor(method, error) {
+        super(`Invalid params for ${method}: ${formatZodIssues(error)}`, -32602);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../core/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IACK;IAAtC,YAAY,OAAe,EAAW,IAAY;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,SAAI,GAAJ,IAAI,CAAQ;QAEhD,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IAC/C,YAAY,MAAc;QACxB,KAAK,CAAC,qBAAqB,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,MAAc,EAAE,KAAiB;QAC3C,KAAK,CAAC,sBAAsB,MAAM,KAAK,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/core/loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Service loader — owns service instances and performs hot, in-process reload via
+ * cache-busting dynamic import. After `git pull`, `restart(name)` loads the new code
+ * from disk without killing the process (same PID).
+ *
+ * Known leak (see docs/architecture.md § Hot reload): each reload imports a fresh
+ * module URL (`?v=<ts>`), and ESM cannot evict the prior generation, so module memory
+ * accumulates. dispose() discipline bounds the *resource* leak, not the *module* leak.
+ */
+import type { EmitterBus } from './bus.js';
+export interface ServiceSpec {
+    name: string;
+    /** Absolute path to the service module exporting createService(). */
+    modulePath: string;
+}
+export declare class ServiceLoader {
+    private readonly bus;
+    private readonly instances;
+    private readonly specs;
+    constructor(bus: EmitterBus);
+    names(): string[];
+    /** Load a service fresh from disk and run its init(). */
+    load(spec: ServiceSpec): Promise<void>;
+    /** Tear down a service: release bus wiring, then dispose its resources. */
+    unload(name: string): Promise<void>;
+    /** Reload one service from disk; other services keep running and retain state. */
+    restart(name: string): Promise<void>;
+    /** Dispose every loaded service (process shutdown / drain). */
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/core/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../core/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAM3C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;gBAE3B,GAAG,EAAE,UAAU;IAE5C,KAAK,IAAI,MAAM,EAAE;IAIjB,yDAAyD;IACnD,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB5C,2EAA2E;IACrE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazC,kFAAkF;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1C,+DAA+D;IACzD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/core/loader.js

@@ -0,0 +1,73 @@
+/**
+ * Service loader — owns service instances and performs hot, in-process reload via
+ * cache-busting dynamic import. After `git pull`, `restart(name)` loads the new code
+ * from disk without killing the process (same PID).
+ *
+ * Known leak (see docs/architecture.md § Hot reload): each reload imports a fresh
+ * module URL (`?v=<ts>`), and ESM cannot evict the prior generation, so module memory
+ * accumulates. dispose() discipline bounds the *resource* leak, not the *module* leak.
+ */
+import { pathToFileURL } from 'node:url';
+import { createLogger } from '../lib/logger.js';
+const log = createLogger('loader');
+export class ServiceLoader {
+    bus;
+    instances = new Map();
+    specs = new Map();
+    constructor(bus) {
+        this.bus = bus;
+    }
+    names() {
+        return [...this.specs.keys()];
+    }
+    /** Load a service fresh from disk and run its init(). */
+    async load(spec) {
+        this.specs.set(spec.name, spec);
+        const url = pathToFileURL(spec.modulePath).href + '?v=' + Date.now();
+        const mod = await import(url);
+        if (typeof mod.createService !== 'function') {
+            throw new Error(`service "${spec.name}" must export createService()`);
+        }
+        const instance = mod.createService();
+        if (instance.name !== spec.name) {
+            log.warn(`service module name "${instance.name}" != spec "${spec.name}"`);
+        }
+        this.instances.set(spec.name, instance);
+        this.bus.beginLoading(spec.name);
+        try {
+            await instance.init(this.bus);
+        }
+        finally {
+            this.bus.endLoading();
+        }
+        log.info(`✅ "${spec.name}" loaded`);
+    }
+    /** Tear down a service: release bus wiring, then dispose its resources. */
+    async unload(name) {
+        const instance = this.instances.get(name);
+        this.bus.releaseService(name);
+        if (instance) {
+            try {
+                await instance.dispose();
+            }
+            catch (err) {
+                log.error(`dispose of "${name}" failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        this.instances.delete(name);
+    }
+    /** Reload one service from disk; other services keep running and retain state. */
+    async restart(name) {
+        const spec = this.specs.get(name);
+        if (!spec)
+            throw new Error(`unknown service: ${name}`);
+        log.info(`restarting "${name}" — reloading from disk`);
+        await this.unload(name);
+        await this.load(spec);
+    }
+    /** Dispose every loaded service (process shutdown / drain). */
+    async disposeAll() {
+        await Promise.allSettled([...this.instances.keys()].map(name => this.unload(name)));
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/core/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../core/loader.ts"],"names":[],"mappings":"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"}

package/dist/core/local.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Local stack — what the CLI boots when no daemon answers on :9000. Loads only the
+ * requested service(s) plus config (the common dependency), runs the call, and the
+ * caller disposes. Keeps a one-off `vargos channel send ...` from needing a daemon.
+ */
+import type { Bus } from './types.js';
+export interface LocalStack {
+    bus: Bus;
+    dispose: () => Promise<void>;
+}
+export declare function bootLocal(serviceNames: string[], rootDir: string, ext: 'ts' | 'js'): Promise<LocalStack>;
+//# sourceMappingURL=local.d.ts.map

package/dist/core/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../core/local.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAsB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAc9G"}

package/dist/core/local.js

@@ -0,0 +1,23 @@
+/**
+ * Local stack — what the CLI boots when no daemon answers on :9000. Loads only the
+ * requested service(s) plus config (the common dependency), runs the call, and the
+ * caller disposes. Keeps a one-off `vargos channel send ...` from needing a daemon.
+ */
+import { EmitterBus } from './bus.js';
+import { ServiceLoader } from './loader.js';
+import { resolveService } from './services.js';
+export async function bootLocal(serviceNames, rootDir, ext) {
+    const bus = new EmitterBus();
+    const loader = new ServiceLoader(bus);
+    // config first, then the requested services (deduped, config never twice). Each name
+    // resolves directly to services/<name>/ — only the requested modules are imported.
+    const wanted = ['config', ...serviceNames.filter(n => n !== 'config')];
+    for (const name of [...new Set(wanted)]) {
+        const spec = resolveService(name, rootDir, ext);
+        if (!spec)
+            throw new Error(`unknown service: ${name}`);
+        await loader.load(spec);
+    }
+    return { bus, dispose: () => loader.disposeAll() };
+}
+//# sourceMappingURL=local.js.map

package/dist/core/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../core/local.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAQ/C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,YAAsB,EAAE,OAAe,EAAE,GAAgB;IACvF,MAAM,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAEtC,qFAAqF;IACrF,mFAAmF;IACnF,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC;IACvE,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;QACvD,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;AACrD,CAAC"}

package/dist/core/rpc-server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * JSON-RPC 2.0 over TCP (surface 3). Newline-delimited requests, localhost-bound.
+ * Dispatch is a thin projection of the registry: every request becomes bus.call().
+ *
+ *   echo '{"jsonrpc":"2.0","method":"memory.search","params":{"query":"..."}}' | nc localhost 9000
+ *
+ * Auth hook: see `authorize()` — a no-op today, the single seam for a future API key.
+ */
+import type { Bus } from './types.js';
+export declare function startRpcServer(bus: Bus, host: string, port: number, socketTimeoutMs?: number): Promise<() => Promise<void>>;
+//# sourceMappingURL=rpc-server.d.ts.map

package/dist/core/rpc-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-server.d.ts","sourceRoot":"","sources":["../../core/rpc-server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAkBtC,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,SAAiB,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAuBnI"}