@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/storage/config.js

@@ -0,0 +1,272 @@
+/**
+ * Storage Configuration Loader and Validator
+ *
+ * Reads `.aiwg/storage.config` (project-local), validates it against the
+ * v1 schema, and returns a typed `StorageConfig`. Absence of the file is
+ * a no-op: every subsystem defaults to `fs` rooted under `.aiwg/`.
+ *
+ * Validation is hand-rolled rather than schema-validator-driven to avoid
+ * adding an `ajv` dependency for a single file. The published JSON
+ * Schema (`.aiwg/architecture/schemas/storage.config.v1.json`) remains
+ * canonical for editor tooling and external consumers.
+ *
+ * @design @.aiwg/architecture/storage-design.md
+ * @issue #934
+ * @issue #953
+ */
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { resolve, isAbsolute, join } from 'path';
+import { homedir } from 'os';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../config/project-artifacts.js';
+import { BACKEND_TYPES, SUBSYSTEM_KEYS, } from './types.js';
+/**
+ * Property names that must never appear at any nesting depth in
+ * `storage.config`. Defense-in-depth against credentials being written
+ * to disk. The published JSON Schema also enforces this; the recursive
+ * runtime walk below catches custom backend extensions that bypass the
+ * static `additionalProperties: false`.
+ */
+export const FORBIDDEN_CREDENTIAL_KEYS = [
+    'token',
+    'password',
+    'secret',
+    'apiKey',
+    'api_key',
+    'accessKey',
+    'accessKeyId',
+    'secretAccessKey',
+];
+const STORAGE_CONFIG_FILENAME = 'storage.config';
+/** Default subsystem-to-relative-path mapping for the `fs` backend. */
+export const DEFAULT_SUBSYSTEM_ROOTS = {
+    memory: 'memory',
+    reflections: 'reflections',
+    kb: 'kb',
+    activity_log: '.', // activity_log is a single file, not a directory
+    provenance: 'provenance',
+    research: 'research',
+    media: 'media',
+    sandbox_identity: 'sandbox-identity',
+};
+/**
+ * Resolve the path where `.aiwg/storage.config` is expected for a given
+ * project root. Does not check existence.
+ */
+export function storageConfigPath(projectRoot) {
+    return projectAiwgPath(projectRoot, STORAGE_CONFIG_FILENAME);
+}
+/**
+ * Load and validate `.aiwg/storage.config` from `projectRoot`.
+ *
+ * Returns `null` if the file is absent (caller falls back to defaults).
+ * Throws a descriptive error for malformed JSON, unsupported version,
+ * unknown subsystem keys, unknown backend types, or any credential-named
+ * property at any depth.
+ */
+export async function loadStorageConfig(projectRoot) {
+    const cfgPath = storageConfigPath(projectRoot);
+    if (!existsSync(cfgPath))
+        return null;
+    let raw;
+    try {
+        raw = await readFile(cfgPath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Failed to read ${cfgPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid JSON in ${cfgPath}: ${err.message}`);
+    }
+    return validateStorageConfig(parsed, cfgPath);
+}
+/**
+ * Validate an already-parsed object as a `StorageConfig`. Exposed for
+ * use by `aiwg doctor` and tests.
+ */
+export function validateStorageConfig(parsed, source = '<input>') {
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${source}: storage config must be an object`);
+    }
+    const obj = parsed;
+    if (obj['version'] !== '1') {
+        throw new Error(`${source}: unsupported schema version ${JSON.stringify(obj['version'])} ` +
+            `(expected "1"). Update the AIWG CLI to read newer config versions.`);
+    }
+    walkRejectingCredentials(obj, source, 'storage');
+    const roots = validateRoots(obj['roots'], source);
+    const backends = validateBackends(obj['backends'], source);
+    let fallback;
+    if (obj['fallback'] !== undefined) {
+        if (obj['fallback'] !== 'cache_and_warn' && obj['fallback'] !== 'block') {
+            throw new Error(`${source}: storage.fallback must be "cache_and_warn" or "block" (got ${JSON.stringify(obj['fallback'])})`);
+        }
+        fallback = obj['fallback'];
+    }
+    const result = { version: '1' };
+    if (roots)
+        result.roots = roots;
+    if (backends)
+        result.backends = backends;
+    if (fallback)
+        result.fallback = fallback;
+    return result;
+}
+function validateRoots(raw, source) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${source}: storage.roots must be an object`);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!isSubsystemKey(k)) {
+            throw new Error(`${source}: roots.${k} is not a known subsystem. ` +
+                `Allowed: ${SUBSYSTEM_KEYS.join(', ')}`);
+        }
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new Error(`${source}: roots.${k} must be a non-empty string path`);
+        }
+        out[k] = v;
+    }
+    return out;
+}
+function validateBackends(raw, source) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${source}: storage.backends must be an object`);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!isSubsystemKey(k)) {
+            throw new Error(`${source}: backends.${k} is not a known subsystem. ` +
+                `Allowed: ${SUBSYSTEM_KEYS.join(', ')}`);
+        }
+        out[k] = validateBackendConfig(v, `${source}: backends.${k}`);
+    }
+    return out;
+}
+function validateBackendConfig(raw, source) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`${source} must be an object`);
+    }
+    const obj = raw;
+    const type = obj['type'];
+    if (typeof type !== 'string' || !BACKEND_TYPES.includes(type)) {
+        throw new Error(`${source}.type must be one of ${BACKEND_TYPES.join(', ')} (got ${JSON.stringify(type)})`);
+    }
+    // Per-backend required fields. Optional fields are passed through as-is
+    // — the adapter is responsible for any further validation it needs.
+    switch (type) {
+        case 'fs':
+            return { type: 'fs' };
+        case 'obsidian':
+            requireString(obj, 'vault', source);
+            return obj;
+        case 'logseq':
+            requireString(obj, 'graph', source);
+            return obj;
+        case 'notion': {
+            const parent = obj['parent'];
+            if (typeof parent !== 'object' || parent === null) {
+                throw new Error(`${source}.parent must be an object with pageId or databaseId`);
+            }
+            const p = parent;
+            const hasPage = typeof p['pageId'] === 'string' && p['pageId'].length > 0;
+            const hasDb = typeof p['databaseId'] === 'string' && p['databaseId'].length > 0;
+            if (hasPage === hasDb) {
+                throw new Error(`${source}.parent must specify exactly one of pageId or databaseId`);
+            }
+            return obj;
+        }
+        case 'anythingllm':
+            requireString(obj, 'baseUrl', source);
+            requireString(obj, 'workspace', source);
+            return obj;
+        case 'fortemi':
+            return obj;
+        case 's3':
+            requireString(obj, 'bucket', source);
+            return obj;
+        case 'webdav':
+            requireString(obj, 'url', source);
+            return obj;
+        default:
+            throw new Error(`${source}: unhandled backend type ${type}`);
+    }
+}
+function requireString(obj, key, source) {
+    const v = obj[key];
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`${source}.${key} must be a non-empty string`);
+    }
+}
+function isSubsystemKey(k) {
+    return SUBSYSTEM_KEYS.includes(k);
+}
+/**
+ * Recursively reject any property whose name appears in
+ * FORBIDDEN_CREDENTIAL_KEYS. Throws on first hit with the full path.
+ */
+export function walkRejectingCredentials(value, source, path) {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            walkRejectingCredentials(value[i], source, `${path}[${i}]`);
+        }
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    for (const [k, v] of Object.entries(value)) {
+        if (FORBIDDEN_CREDENTIAL_KEYS.includes(k)) {
+            throw new Error(`${source}: forbidden credential property "${path}.${k}" — ` +
+                `tokens, passwords, and API keys must come from environment variables, never from storage.config.`);
+        }
+        walkRejectingCredentials(v, source, `${path}.${k}`);
+    }
+}
+/**
+ * Resolve the absolute filesystem path for an `fs`-backed subsystem,
+ * applying `roots` overrides if present. Used by the fs adapter.
+ *
+ * Resolution order:
+ *   1. `roots[subsystem]` if set, expanding `~` and accepting absolute paths
+ *   2. `<resolved-aiwg-artifact-dir>/<DEFAULT_SUBSYSTEM_ROOTS[subsystem]>`
+ */
+export function resolveSubsystemRoot(subsystem, projectRoot, config) {
+    const override = config?.roots?.[subsystem];
+    if (override)
+        return expandPath(override, projectRoot);
+    return join(resolveProjectAiwgDir(projectRoot), DEFAULT_SUBSYSTEM_ROOTS[subsystem]);
+}
+/**
+ * Async variant used by runtime adapter creation. For memory only, it can
+ * resolve a user-level private project memory root from ~/.aiwg/projects when
+ * no project-local `.aiwg` exists. Explicit storage.config roots still win.
+ */
+export async function resolveSubsystemRootRuntime(subsystem, projectRoot, config) {
+    const override = config?.roots?.[subsystem];
+    if (override)
+        return expandPath(override, projectRoot);
+    if (subsystem === 'memory') {
+        const { resolveProjectMemoryRoot } = await import('../memory/project-registry.js');
+        const resolved = await resolveProjectMemoryRoot(projectRoot);
+        return resolved.root;
+    }
+    return join(resolveProjectAiwgDir(projectRoot), DEFAULT_SUBSYSTEM_ROOTS[subsystem]);
+}
+function expandPath(p, projectRoot) {
+    if (p.startsWith('~/'))
+        return resolve(homedir(), p.slice(2));
+    if (p === '~')
+        return homedir();
+    if (isAbsolute(p))
+        return p;
+    return resolve(projectRoot, p);
+}
+//# sourceMappingURL=config.js.map

package/dist/src/storage/index.js

@@ -0,0 +1,108 @@
+/**
+ * Storage Adapter Registry
+ *
+ * `resolveStorage(subsystem)` is the consumer-facing entry point. Loads
+ * `.aiwg/storage.config` lazily, picks the configured backend per
+ * subsystem, and memoizes the adapter instance for the lifetime of the
+ * process.
+ *
+ * @design @.aiwg/architecture/storage-design.md
+ * @issue #934
+ * @issue #953
+ */
+import { loadStorageConfig, resolveSubsystemRootRuntime } from './config.js';
+import { FilesystemAdapter } from './backends/fs.js';
+import { ObsidianAdapter } from './backends/obsidian.js';
+import { LogseqAdapter } from './backends/logseq.js';
+import { FortemiAdapter } from './backends/fortemi.js';
+export { SUBSYSTEM_KEYS, BACKEND_TYPES, } from './types.js';
+export { loadStorageConfig, storageConfigPath, validateStorageConfig, resolveSubsystemRoot, resolveSubsystemRootRuntime, walkRejectingCredentials, FORBIDDEN_CREDENTIAL_KEYS, DEFAULT_SUBSYSTEM_ROOTS, } from './config.js';
+export { FilesystemAdapter } from './backends/fs.js';
+export { ObsidianAdapter } from './backends/obsidian.js';
+export { LogseqAdapter } from './backends/logseq.js';
+export { FortemiAdapter } from './backends/fortemi.js';
+let state = null;
+/**
+ * Initialize or reset the registry for a given project root. Most
+ * callers use the implicit lazy initialization triggered by
+ * `resolveStorage()`; explicit init is useful for tests and for the
+ * `aiwg storage` CLI.
+ */
+export async function initStorage(projectRoot = process.cwd()) {
+    const config = await loadStorageConfig(projectRoot);
+    state = {
+        projectRoot,
+        config,
+        adapters: new Map(),
+        loaded: true,
+    };
+}
+/** Reset memoized state. Test-only escape hatch. */
+export function resetStorage() {
+    state = null;
+}
+/**
+ * Return the adapter for a subsystem. Loads `.aiwg/storage.config`
+ * lazily on first call.
+ */
+export async function resolveStorage(subsystem) {
+    if (!state || !state.loaded) {
+        await initStorage(process.cwd());
+    }
+    const s = state;
+    const cached = s.adapters.get(subsystem);
+    if (cached)
+        return cached;
+    const adapter = await createAdapter(subsystem, s);
+    s.adapters.set(subsystem, adapter);
+    return adapter;
+}
+/**
+ * Return the loaded config (or null if `.aiwg/storage.config` does not
+ * exist). Triggers a load if not yet initialized. Used by the CLI.
+ */
+export async function getLoadedConfig(projectRoot = process.cwd()) {
+    if (!state || state.projectRoot !== projectRoot) {
+        await initStorage(projectRoot);
+    }
+    return state.config;
+}
+/**
+ * Build the adapter for a subsystem given the current registry state.
+ * Pure factory — no I/O beyond the path resolution the backend itself
+ * performs in its constructor.
+ */
+async function createAdapter(subsystem, s) {
+    const backend = s.config?.backends?.[subsystem] ?? { type: 'fs' };
+    switch (backend.type) {
+        case 'fs': {
+            const root = await resolveSubsystemRootRuntime(subsystem, s.projectRoot, s.config);
+            return new FilesystemAdapter(root);
+        }
+        case 'obsidian':
+            return new ObsidianAdapter(backend);
+        case 'logseq':
+            return new LogseqAdapter(backend);
+        case 'fortemi':
+            return new FortemiAdapter({ subsystem, config: backend });
+        case 'notion':
+        case 'anythingllm':
+        case 's3':
+        case 'webdav': {
+            const stubIssues = {
+                notion: '#959',
+                anythingllm: '#960',
+                s3: '#962',
+                webdav: '#963',
+            };
+            throw new Error(`storage: backend "${backend.type}" is declared in storage.config but not yet implemented. ` +
+                `Tracked at ${stubIssues[backend.type]} — see https://git.integrolabs.net/roctinam/aiwg/issues/${stubIssues[backend.type].slice(1)} for status.`);
+        }
+        default: {
+            // Exhaustiveness check
+            const _exhaustive = backend;
+            throw new Error(`storage: unhandled backend type ${_exhaustive.type}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/storage/subsystem-cli.js

@@ -0,0 +1,201 @@
+/**
+ * Generic subsystem CLI runner.
+ *
+ * Provides path/list/get/put/delete/append-log subcommands for any
+ * storage subsystem. Used by `aiwg memory` (#966), `aiwg reflections`
+ * (#967), and any future per-subsystem CLI wrappers — keeping the
+ * shared logic in one place rather than duplicating it.
+ *
+ * Each subsystem-specific CLI is a 5-line wrapper:
+ *
+ *   import { runSubsystemCli } from '../storage/subsystem-cli.js';
+ *   export async function main(args: string[]): Promise<void> {
+ *     await runSubsystemCli('memory', args);
+ *   }
+ *
+ * @design @.aiwg/architecture/storage-design.md (§4)
+ * @issue #934
+ * @issue #966
+ * @issue #967
+ */
+import { getLoadedConfig, resolveStorage } from './index.js';
+import { resolveSubsystemRootRuntime } from './config.js';
+export async function runSubsystemCli(subsystem, args, opts = {}) {
+    const subcommand = args[0];
+    const subArgs = args.slice(1);
+    const display = opts.displayName ?? subsystem;
+    switch (subcommand) {
+        case 'path':
+            await handlePath(subsystem, display, subArgs);
+            break;
+        case 'list':
+            await handleList(subsystem, display, subArgs);
+            break;
+        case 'get':
+            await handleGet(subsystem, display, subArgs);
+            break;
+        case 'put':
+            await handlePut(subsystem, display, subArgs);
+            break;
+        case 'delete':
+            await handleDelete(subsystem, display, subArgs);
+            break;
+        case 'append-log':
+            await handleAppendLog(subsystem, display, subArgs);
+            break;
+        default:
+            printUsage(subsystem, display);
+            if (subcommand) {
+                throw new Error(`Unknown ${display} subcommand: ${subcommand}`);
+            }
+    }
+}
+async function handlePath(subsystem, display, args) {
+    const subpath = args.find((a) => !a.startsWith('--'));
+    const json = args.includes('--json');
+    const projectRoot = process.cwd();
+    const config = await getLoadedConfig(projectRoot);
+    const backend = config?.backends?.[subsystem]?.type ?? 'fs';
+    if (backend !== 'fs') {
+        if (json) {
+            console.log(JSON.stringify({
+                backend,
+                note: `${display} subsystem uses backend "${backend}" — physical filesystem path is not applicable. Use \`aiwg ${display} get/list\` instead.`,
+            }, null, 2));
+        }
+        else {
+            console.log(`${display} backend: ${backend}`);
+            console.log(`  (filesystem path not applicable for this backend; use \`aiwg ${display} get/list\`)`);
+        }
+        return;
+    }
+    const root = await resolveSubsystemRootRuntime(subsystem, projectRoot, config);
+    const fullPath = subpath ? `${root}/${subpath}` : root;
+    if (json) {
+        console.log(JSON.stringify({ backend, root, path: fullPath }, null, 2));
+    }
+    else {
+        console.log(fullPath);
+    }
+}
+async function handleList(subsystem, display, args) {
+    let prefix = '';
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--prefix')
+            prefix = args[++i] ?? '';
+        else if (args[i] === '--json')
+            json = true;
+    }
+    const adapter = await resolveStorage(subsystem);
+    const entries = await adapter.list(prefix);
+    if (json) {
+        console.log(JSON.stringify(entries.map((e) => ({
+            path: e.path,
+            size: e.size,
+            modifiedAt: e.modifiedAt?.toISOString(),
+        })), null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log(`No ${display} entries${prefix ? ` matching prefix "${prefix}"` : ''}.`);
+        return;
+    }
+    for (const e of entries)
+        console.log(e.path);
+}
+async function handleGet(subsystem, display, args) {
+    const path = args[0];
+    if (!path)
+        throw new Error(`Usage: aiwg ${display} get <path>`);
+    const adapter = await resolveStorage(subsystem);
+    const content = await adapter.read(path);
+    if (content === null)
+        throw new Error(`${display} entry not found: ${path}`);
+    process.stdout.write(content);
+}
+async function handlePut(subsystem, display, args) {
+    const path = args[0];
+    if (!path) {
+        throw new Error(`Usage: aiwg ${display} put <path>\n` +
+            `  Reads content from stdin. Creates parent directories. Overwrites existing.`);
+    }
+    const content = await readStdin();
+    const adapter = await resolveStorage(subsystem);
+    await adapter.write(path, content);
+    console.log(`Wrote ${content.length} bytes to ${display}:${path}`);
+}
+async function handleDelete(subsystem, display, args) {
+    const path = args[0];
+    if (!path)
+        throw new Error(`Usage: aiwg ${display} delete <path>`);
+    const adapter = await resolveStorage(subsystem);
+    await adapter.delete(path);
+    console.log(`Deleted ${display}:${path} (no-op if missing)`);
+}
+async function handleAppendLog(subsystem, display, args) {
+    const logPath = args[0];
+    if (!logPath) {
+        throw new Error(`Usage: aiwg ${display} append-log <log-path>\n` +
+            `  Reads a single JSON object from stdin and appends it as one JSONL line.`);
+    }
+    const stdinContent = (await readStdin()).trim();
+    if (stdinContent.length === 0) {
+        throw new Error('append-log: stdin must contain a single JSON object (got empty input)');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stdinContent);
+    }
+    catch (err) {
+        throw new Error(`append-log: stdin must be valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('append-log: stdin must be a single JSON object (not an array, not a primitive)');
+    }
+    const line = JSON.stringify(parsed) + '\n';
+    const adapter = await resolveStorage(subsystem);
+    if (typeof adapter.append === 'function') {
+        const existing = (await adapter.read(logPath)) ?? '';
+        if (existing.length > 0 && !existing.endsWith('\n')) {
+            await adapter.append(logPath, '\n');
+        }
+        await adapter.append(logPath, line);
+    }
+    else {
+        const existing = (await adapter.read(logPath)) ?? '';
+        const trailing = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+        await adapter.write(logPath, existing + trailing + line);
+    }
+    console.log(`Appended JSONL event to ${display}:${logPath}`);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+function printUsage(subsystem, display) {
+    console.log(`Usage: aiwg ${display} <subcommand>
+
+Subcommands:
+  path [<subpath>] [--json]      Resolved physical path (fs backend)
+  list [--prefix <p>] [--json]   List entries through the adapter
+  get <path>                     Read entry to stdout
+  put <path>                     Write stdin to entry
+  delete <path>                  Delete entry (no-op if missing)
+  append-log <log-path>          Append a JSON object from stdin as JSONL
+                                 (atomic when the backend supports adapter.append)
+
+Examples:
+  aiwg ${display} path
+  aiwg ${display} list --prefix some/
+  aiwg ${display} get some/page.md
+  echo "# page" | aiwg ${display} put some/page.md
+  echo '{"event":"x"}' | aiwg ${display} append-log some/log.jsonl
+
+The ${display} subsystem persists at .aiwg/${subsystem}/ on the default fs backend.
+Configure .aiwg/storage.config to redirect (#934).`);
+}
+//# sourceMappingURL=subsystem-cli.js.map

package/dist/src/storage/types.js

@@ -0,0 +1,33 @@
+/**
+ * Storage Adapter Types
+ *
+ * Public contracts for the AIWG storage abstraction. Consumers use
+ * `resolveStorage(subsystem)` to obtain a backend-specific adapter
+ * conforming to `StorageAdapter`.
+ *
+ * @design @.aiwg/architecture/storage-design.md
+ * @schema @.aiwg/architecture/schemas/storage.config.v1.json
+ * @issue #934
+ * @issue #953
+ */
+export const SUBSYSTEM_KEYS = [
+    'memory',
+    'reflections',
+    'kb',
+    'activity_log',
+    'provenance',
+    'research',
+    'media',
+    'sandbox_identity',
+];
+export const BACKEND_TYPES = [
+    'fs',
+    'obsidian',
+    'logseq',
+    'notion',
+    'anythingllm',
+    'fortemi',
+    's3',
+    'webdav',
+];
+//# sourceMappingURL=types.js.map