@vxnus/siduri 0.0.5 → 0.0.6

package/README.md

@@ -1,47 +1,66 @@
 # @vxnus/siduri
 
-Experimental CLI for creating and configuring Siduri companions.
+Experimental CLI for creating, diagnosing, and managing standalone Siduri companions powered by the `@siduri-x/*` organ ecosystem.
 
 Requires Node.js 20 or newer.
 
 ```bash
-npx @vxnus/siduri@0.0.5 create
+npx @vxnus/siduri create my-companion
 ```
 
-The companion name becomes the project directory. For example, answering
-`My Companion` creates `./my-companion/siduri.config.json` from the current
-directory.
+## Features
 
-The wizard configures the required Brain and Memory organs, then lets you
-enable or disable Voice, Knowledge, Behavior, Body, and Vision. Knowledge can
-come from an installed E pack, an E Hub distribution, or a hosted provider.
+- **Manifest-Driven Organ Discovery**: Dynamically discovers installed `@siduri-x/*` organs and generates custom, standalone ESM instance code.
+- **Zero Monolithic Bundling**: Scaffolds standard Node.js ESM projects with explicit dependency trees.
+- **Diagnostics (`siduri doctor`)**: Runs environment variable validation, external service checks, database health probes, and organ-specific assertions.
+- **Database Migrations (`siduri db push`)**: Inspects database-owning organs (such as `@siduri-x/memory`) and executes SQL migrations with SHA-256 integrity checksums.
 
-Brain providers:
+## CLI Usage
 
-- **OpenRouter** — managed model routing using `OPENROUTER_API_KEY`.
-- **OpenAI-compatible API** — a custom `baseUrl`, model ID, and API-key
-  environment variable.
+### 1. Create a Standalone Companion
 
-Memory currently uses PostgreSQL. The wizard lets you choose Local PostgreSQL,
-Neon, Supabase, or another PostgreSQL provider; all use `DATABASE_URL`. SQLite
-is shown as a future option but is not selectable in this release.
+```bash
+npx @vxnus/siduri create [directory]
+```
+
+The interactive wizard allows you to name your companion and select any combination of available `@siduri-x/*` organs. It generates:
+
+```text
+my-companion/
+├── package.json          # ESM package referencing only selected @siduri-x/* organs
+├── siduri.config.json    # Selected organ configurations
+├── siduri.schema.json    # Composed JSON Schema from organ manifests
+├── .env.example          # Only environment variables required by selected organs
+├── README.md             # Instance-specific guide
+└── src/
+    └── index.js          # Direct runtime bootstrapping with explicit organ factories
+```
+
+### 2. Run Diagnostics
+
+```bash
+npx @vxnus/siduri doctor [directory]
+```
+
+Inspects active configuration, checks required/optional environment variables, and executes health probes.
+
+### 3. Apply Migrations
+
+```bash
+npx @vxnus/siduri db push [directory]
+```
+
+Runs database migrations exclusively for configured database organs. If no database organs are selected (e.g. Brain + Hands), reports that no migrations are needed.
 
-The wizard creates a project directory from the companion name, writes
-`siduri.config.json`, copies the Siduri runtime, and installs the runtime
-dependencies. API keys are never written to the configuration file. Optional
-organs can be configured as `{ "provider": "none" }`; Brain and Memory remain
-required.
+## Local Development
 
-After setup, start the generated instance with:
+From the repository root:
 
 ```bash
-cd my-companion
-npm run start
+pnpm --filter @vxnus/siduri build
+pnpm --filter @vxnus/siduri test
 ```
 
-For local development, build the CLI from the repository root with
-`pnpm --filter @vxnus/siduri build`. For the full architecture, see the
-[CLI documentation](../docs/cli.md) and
-[configuration reference](../docs/configuration.md).
+## License
 
-This release is experimental and is not intended for production use.
+Licensed under the [Apache License, Version 2.0](./LICENSE).

package/dist/clean-machine-e2e.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clean-machine-e2e.test.js

@@ -0,0 +1,222 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const generator_1 = require("./generator");
+const discovery_1 = require("./discovery");
+describe('Phase 5: Clean-Machine Distribution & E2E Integration Suite', () => {
+    const repoRoot = node_path_1.default.resolve(__dirname, '../..');
+    const tempPackDir = node_path_1.default.resolve(__dirname, '../temp-packs-e2e');
+    const cleanMachineRoot = node_path_1.default.resolve(__dirname, '../temp-clean-machine-e2e');
+    const ALL_CANONICAL_PACKAGES = [
+        { filter: '@siduri-x/core', tarName: 'siduri-x-core-1.0.0.tgz', isOrgan: false },
+        { filter: '@siduri-x/brain', tarName: 'siduri-x-brain-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/memory', tarName: 'siduri-x-memory-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/knowledge', tarName: 'siduri-x-knowledge-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/behavior', tarName: 'siduri-x-behavior-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/ear', tarName: 'siduri-x-ear-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/vision', tarName: 'siduri-x-vision-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/hands', tarName: 'siduri-x-hands-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/body', tarName: 'siduri-x-body-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/voice', tarName: 'siduri-x-voice-1.0.0.tgz', isOrgan: true },
+        { filter: '@siduri-x/observation', tarName: 'siduri-x-observation-1.0.0.tgz', isOrgan: true },
+        { filter: '@vxnus/siduri', tarName: 'vxnus-siduri-0.0.6.tgz', isOrgan: false },
+    ];
+    beforeAll(() => {
+        // 1. Prepare clean directories
+        if (node_fs_1.default.existsSync(tempPackDir))
+            node_fs_1.default.rmSync(tempPackDir, { recursive: true, force: true });
+        if (node_fs_1.default.existsSync(cleanMachineRoot))
+            node_fs_1.default.rmSync(cleanMachineRoot, { recursive: true, force: true });
+        node_fs_1.default.mkdirSync(tempPackDir, { recursive: true });
+        node_fs_1.default.mkdirSync(cleanMachineRoot, { recursive: true });
+        // 2. Build all packages in repo
+        (0, node_child_process_1.execSync)('pnpm build', { cwd: repoRoot, stdio: 'pipe' });
+        // 3. Pack each canonical package into tempPackDir
+        for (const pkg of ALL_CANONICAL_PACKAGES) {
+            (0, node_child_process_1.execSync)(`pnpm --filter ${pkg.filter} pack --pack-destination ${tempPackDir}`, {
+                cwd: repoRoot,
+                stdio: 'pipe',
+            });
+        }
+    }, 90000);
+    afterAll(() => {
+        if (node_fs_1.default.existsSync(tempPackDir))
+            node_fs_1.default.rmSync(tempPackDir, { recursive: true, force: true });
+        if (node_fs_1.default.existsSync(cleanMachineRoot))
+            node_fs_1.default.rmSync(cleanMachineRoot, { recursive: true, force: true });
+    });
+    describe('Phase 5A: Package Artifact Verification', () => {
+        test('all 12 packages produce valid tarballs', () => {
+            for (const pkg of ALL_CANONICAL_PACKAGES) {
+                const tarPath = node_path_1.default.join(tempPackDir, pkg.tarName);
+                expect(node_fs_1.default.existsSync(tarPath)).toBe(true);
+            }
+        });
+        test('packed package.json files have zero workspace:* or link: dependencies', () => {
+            for (const pkg of ALL_CANONICAL_PACKAGES) {
+                const tarPath = node_path_1.default.join(tempPackDir, pkg.tarName);
+                const pkgJsonRaw = (0, node_child_process_1.execSync)(`tar -xzf ${tarPath} -O package/package.json`, { encoding: 'utf8' });
+                const pkgJson = JSON.parse(pkgJsonRaw);
+                const allDeps = {
+                    ...(pkgJson.dependencies || {}),
+                    ...(pkgJson.peerDependencies || {}),
+                };
+                for (const [depName, version] of Object.entries(allDeps)) {
+                    if (typeof version === 'string') {
+                        expect(version.startsWith('workspace:')).toBe(false);
+                        expect(version.startsWith('link:')).toBe(false);
+                        expect(version.includes('../')).toBe(false);
+                    }
+                }
+            }
+        });
+        test('every organ package tarball contains organ-manifest.json and dist files', () => {
+            const organPackages = ALL_CANONICAL_PACKAGES.filter((p) => p.isOrgan);
+            for (const pkg of organPackages) {
+                const tarPath = node_path_1.default.join(tempPackDir, pkg.tarName);
+                const listing = (0, node_child_process_1.execSync)(`tar -tzf ${tarPath}`, { encoding: 'utf8' }).split('\n');
+                expect(listing.some((line) => line.includes('package/organ-manifest.json'))).toBe(true);
+                expect(listing.some((line) => line.includes('package/dist/index.js'))).toBe(true);
+                expect(listing.some((line) => line.includes('package/dist/index.d.ts'))).toBe(true);
+            }
+        });
+        test('memory organ tarball packages migrations/001_initial_schema.sql', () => {
+            const memoryTarPath = node_path_1.default.join(tempPackDir, 'siduri-x-memory-1.0.0.tgz');
+            const listing = (0, node_child_process_1.execSync)(`tar -tzf ${memoryTarPath}`, { encoding: 'utf8' });
+            expect(listing).toContain('package/migrations/001_initial_schema.sql');
+        });
+    });
+    describe('Phase 5B & 5C & 5G: Clean-Machine Installation & Isolation Acceptance', () => {
+        const registry = discovery_1.OrganRegistry.discover([node_path_1.default.resolve(repoRoot, 'packages/organs')]);
+        const brain = registry.get('brain');
+        const hands = registry.get('hands');
+        const memory = registry.get('memory');
+        test('Clean Composition 1: Brain only instance installs, starts, runs doctor and db push', () => {
+            const instanceDir = node_path_1.default.join(cleanMachineRoot, 'inst-brain-only');
+            node_fs_1.default.mkdirSync(node_path_1.default.join(instanceDir, 'src'), { recursive: true });
+            const files = (0, generator_1.generateInstanceFiles)({
+                name: 'CleanBrainOnly',
+                selectedManifests: [brain],
+            });
+            // Write instance files referencing packed tarballs directly for true clean machine install
+            const pkgObj = JSON.parse(files['package.json']);
+            pkgObj.dependencies = {
+                '@siduri-x/core': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-core-1.0.0.tgz')}`,
+                '@siduri-x/brain': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-brain-1.0.0.tgz')}`,
+            };
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'package.json'), JSON.stringify(pkgObj, null, 2) + '\n');
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.config.json'), files['siduri.config.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.schema.json'), files['siduri.schema.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, '.env.example'), files['.env.example']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'README.md'), files['README.md']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'src/index.js'), files['src/index.js']);
+            // 1. Run npm install in isolated directory
+            (0, node_child_process_1.execSync)('npm install --no-audit --no-fund', { cwd: instanceDir, stdio: 'pipe' });
+            // 2. Assert unselected organs are NOT in node_modules
+            expect(node_fs_1.default.existsSync(node_path_1.default.join(instanceDir, 'node_modules/@siduri-x/memory'))).toBe(false);
+            expect(node_fs_1.default.existsSync(node_path_1.default.join(instanceDir, 'node_modules/@siduri-x/hands'))).toBe(false);
+            expect(node_fs_1.default.existsSync(node_path_1.default.join(instanceDir, 'node_modules/@siduri-x/voice'))).toBe(false);
+            expect(node_fs_1.default.existsSync(node_path_1.default.join(instanceDir, 'siduri-x-runtime.js'))).toBe(false);
+            // 3. Run node src/index.js (starts cleanly without PostgreSQL or unselected organs)
+            const startOutput = (0, node_child_process_1.execSync)('node src/index.js', { cwd: instanceDir, encoding: 'utf8' });
+            expect(startOutput).toContain('✓ Siduri [CleanBrainOnly] initialized with [Brain].');
+            // 4. Verify doctor from standalone directory
+            const doctorPass = (0, node_child_process_1.execSync)(`node ${node_path_1.default.resolve(repoRoot, 'cli/dist/index.js')} doctor`, {
+                cwd: instanceDir,
+                env: { ...process.env, OPENROUTER_API_KEY: 'test-key-clean' },
+                encoding: 'utf8',
+            });
+            expect(doctorPass).toContain('Result: PASS');
+            expect(doctorPass).toContain('Database');
+            expect(doctorPass).toContain('Not required by current composition');
+            // 5. Verify db push from standalone directory
+            const dbPushOutput = (0, node_child_process_1.execSync)(`node ${node_path_1.default.resolve(repoRoot, 'cli/dist/index.js')} db push`, {
+                cwd: instanceDir,
+                encoding: 'utf8',
+            });
+            expect(dbPushOutput).toContain('No database migrations are required by this instance.');
+        }, 60000);
+        test('Clean Composition 2: Brain + Hands installs and runs doctor verifying ACTION_POLICY_SECRET', () => {
+            const instanceDir = node_path_1.default.join(cleanMachineRoot, 'inst-brain-hands');
+            node_fs_1.default.mkdirSync(node_path_1.default.join(instanceDir, 'src'), { recursive: true });
+            const files = (0, generator_1.generateInstanceFiles)({
+                name: 'CleanBrainHands',
+                selectedManifests: [brain, hands],
+            });
+            const pkgObj = JSON.parse(files['package.json']);
+            pkgObj.dependencies = {
+                '@siduri-x/core': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-core-1.0.0.tgz')}`,
+                '@siduri-x/brain': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-brain-1.0.0.tgz')}`,
+                '@siduri-x/hands': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-hands-1.0.0.tgz')}`,
+            };
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'package.json'), JSON.stringify(pkgObj, null, 2) + '\n');
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.config.json'), files['siduri.config.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.schema.json'), files['siduri.schema.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, '.env.example'), files['.env.example']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'README.md'), files['README.md']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'src/index.js'), files['src/index.js']);
+            (0, node_child_process_1.execSync)('npm install --no-audit --no-fund', { cwd: instanceDir, stdio: 'pipe' });
+            expect(node_fs_1.default.existsSync(node_path_1.default.join(instanceDir, 'node_modules/@siduri-x/memory'))).toBe(false);
+            const startOutput = (0, node_child_process_1.execSync)('node src/index.js', { cwd: instanceDir, encoding: 'utf8' });
+            expect(startOutput).toContain('✓ Siduri [CleanBrainHands] initialized with [Brain, Hands].');
+            const doctorOutput = (0, node_child_process_1.execSync)(`node ${node_path_1.default.resolve(repoRoot, 'cli/dist/index.js')} doctor`, {
+                cwd: instanceDir,
+                env: {
+                    ...process.env,
+                    OPENROUTER_API_KEY: 'test-key-clean',
+                    ACTION_POLICY_SECRET: 'test-secret-clean',
+                },
+                encoding: 'utf8',
+            });
+            expect(doctorOutput).toContain('ACTION_POLICY_SECRET');
+            expect(doctorOutput).toContain('Result: PASS');
+        }, 60000);
+        test('Clean Composition 3: Brain + Memory discovers packaged migrations and detects DATABASE_URL', () => {
+            const instanceDir = node_path_1.default.join(cleanMachineRoot, 'inst-brain-memory');
+            node_fs_1.default.mkdirSync(node_path_1.default.join(instanceDir, 'src'), { recursive: true });
+            const files = (0, generator_1.generateInstanceFiles)({
+                name: 'CleanBrainMemory',
+                selectedManifests: [brain, memory],
+            });
+            const pkgObj = JSON.parse(files['package.json']);
+            pkgObj.dependencies = {
+                '@siduri-x/core': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-core-1.0.0.tgz')}`,
+                '@siduri-x/brain': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-brain-1.0.0.tgz')}`,
+                '@siduri-x/memory': `file:${node_path_1.default.join(tempPackDir, 'siduri-x-memory-1.0.0.tgz')}`,
+            };
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'package.json'), JSON.stringify(pkgObj, null, 2) + '\n');
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.config.json'), files['siduri.config.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'siduri.schema.json'), files['siduri.schema.json']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, '.env.example'), files['.env.example']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'README.md'), files['README.md']);
+            node_fs_1.default.writeFileSync(node_path_1.default.join(instanceDir, 'src/index.js'), files['src/index.js']);
+            (0, node_child_process_1.execSync)('npm install --no-audit --no-fund', { cwd: instanceDir, stdio: 'pipe' });
+            // Verify migrations exist inside node_modules/@siduri-x/memory/migrations
+            const installedMigrationsPath = node_path_1.default.join(instanceDir, 'node_modules/@siduri-x/memory/migrations/001_initial_schema.sql');
+            expect(node_fs_1.default.existsSync(installedMigrationsPath)).toBe(true);
+            // Doctor detects database requirement
+            let doctorOutput = '';
+            try {
+                doctorOutput = (0, node_child_process_1.execSync)(`node ${node_path_1.default.resolve(repoRoot, 'cli/dist/index.js')} doctor`, {
+                    cwd: instanceDir,
+                    env: {
+                        ...process.env,
+                        OPENROUTER_API_KEY: 'test-key-clean',
+                        DATABASE_URL: '', // deliberately empty to test requirement detection
+                    },
+                    encoding: 'utf8',
+                });
+            }
+            catch (err) {
+                doctorOutput = (err.stdout || '') + (err.stderr || '');
+            }
+            expect(doctorOutput).toContain('DATABASE_URL is not configured');
+            expect(doctorOutput).toContain('Result: FAIL');
+        }, 60000);
+    });
+});

package/dist/db.d.ts

@@ -0,0 +1,25 @@
+export declare function redactDatabaseUrl(url: string): string;
+export interface MigrationFile {
+    name: string;
+    fullPath: string;
+    sql: string;
+    checksum: string;
+}
+export interface MigrationRecord {
+    id: number;
+    name: string;
+    checksum: string;
+    applied_at: string;
+}
+export interface DbPushOptions {
+    projectDir?: string;
+    connectionString?: string;
+    env?: Record<string, string | undefined>;
+}
+export interface DbPushResult {
+    status: 'NOOP' | 'APPLIED' | 'UP_TO_DATE';
+    appliedMigrations: string[];
+    skippedMigrations: string[];
+    message: string;
+}
+export declare function runDbPush(options?: DbPushOptions): Promise<DbPushResult>;

package/dist/db.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactDatabaseUrl = redactDatabaseUrl;
+exports.runDbPush = runDbPush;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const pg_1 = require("pg");
+const discovery_1 = require("./discovery");
+function redactDatabaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password) {
+            parsed.password = '***';
+        }
+        return parsed.toString();
+    }
+    catch {
+        return 'postgres://***:***@...';
+    }
+}
+async function runDbPush(options = {}) {
+    const projectDir = options.projectDir ? node_path_1.default.resolve(options.projectDir) : process.cwd();
+    const configPath = node_path_1.default.join(projectDir, 'siduri.config.json');
+    if (!node_fs_1.default.existsSync(configPath)) {
+        throw new Error(`siduri.config.json not found at ${projectDir}. Make sure you are in a Siduri instance directory.`);
+    }
+    const config = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf8'));
+    const configuredOrgans = config.organs || {};
+    // 1. Discover manifests of configured organs
+    const registry = discovery_1.OrganRegistry.discover([
+        node_path_1.default.join(projectDir, 'node_modules/@siduri-x'),
+        node_path_1.default.resolve(__dirname, '../../packages/organs'),
+        node_path_1.default.resolve(process.cwd(), 'packages/organs'),
+    ]);
+    const databaseOrgans = [];
+    for (const [key] of Object.entries(configuredOrgans)) {
+        const manifest = registry.get(key) || registry.getAll().find((m) => m.configKey === key || m.organType === key);
+        if (manifest && manifest.database && manifest.database.migrationsDir) {
+            // Resolve migrations directory relative to the organ package
+            const candidatePaths = [
+                node_path_1.default.resolve(projectDir, 'node_modules', manifest.name, manifest.database.migrationsDir),
+                node_path_1.default.resolve(__dirname, '../../packages/organs', manifest.organType, manifest.database.migrationsDir),
+                node_path_1.default.resolve(process.cwd(), 'packages/organs', manifest.organType, manifest.database.migrationsDir),
+            ];
+            const resolvedDir = candidatePaths.find((p) => node_fs_1.default.existsSync(p));
+            if (resolvedDir) {
+                databaseOrgans.push({
+                    organType: manifest.organType,
+                    manifest,
+                    migrationsDir: resolvedDir,
+                });
+            }
+        }
+    }
+    if (databaseOrgans.length === 0) {
+        return {
+            status: 'NOOP',
+            appliedMigrations: [],
+            skippedMigrations: [],
+            message: 'No database migrations are required by this instance.',
+        };
+    }
+    // 2. Resolve DATABASE_URL
+    const connectionString = options.connectionString ||
+        options.env?.DATABASE_URL ||
+        process.env.DATABASE_URL;
+    if (!connectionString) {
+        throw new Error('DATABASE_URL is required to run database migrations. Set it in .env or environment.');
+    }
+    const pool = new pg_1.Pool({
+        connectionString,
+        connectionTimeoutMillis: 5000,
+    });
+    const client = await pool.connect();
+    try {
+        // 3. Ensure migrations table exists
+        await client.query(`
+      CREATE TABLE IF NOT EXISTS siduri_migrations (
+        id SERIAL PRIMARY KEY,
+        name VARCHAR(255) UNIQUE NOT NULL,
+        checksum VARCHAR(64) NOT NULL,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+        // 4. Fetch applied migrations
+        const existingRes = await client.query('SELECT name, checksum FROM siduri_migrations ORDER BY id ASC;');
+        const appliedMap = new Map();
+        for (const row of existingRes.rows) {
+            appliedMap.set(row.name, row.checksum);
+        }
+        // 5. Gather all migration files across database organs in deterministic order
+        const allMigrationFiles = [];
+        for (const item of databaseOrgans) {
+            const files = node_fs_1.default.readdirSync(item.migrationsDir).filter((f) => f.endsWith('.sql')).sort();
+            for (const file of files) {
+                const fullPath = node_path_1.default.join(item.migrationsDir, file);
+                const sql = node_fs_1.default.readFileSync(fullPath, 'utf8');
+                const checksum = (0, node_crypto_1.createHash)('sha256').update(sql).digest('hex');
+                allMigrationFiles.push({
+                    name: `${item.organType}/${file}`,
+                    fullPath,
+                    sql,
+                    checksum,
+                });
+            }
+        }
+        allMigrationFiles.sort((a, b) => a.name.localeCompare(b.name));
+        const appliedList = [];
+        const skippedList = [];
+        for (const migration of allMigrationFiles) {
+            const recordedChecksum = appliedMap.get(migration.name);
+            if (recordedChecksum !== undefined) {
+                if (recordedChecksum !== migration.checksum) {
+                    throw new Error(`Migration checksum mismatch for ${migration.name}! Recorded: ${recordedChecksum.slice(0, 8)}, Current: ${migration.checksum.slice(0, 8)}. Refusing to apply modified migration.`);
+                }
+                skippedList.push(migration.name);
+            }
+            else {
+                // Apply migration in transaction
+                await client.query('BEGIN');
+                try {
+                    await client.query(migration.sql);
+                    await client.query('INSERT INTO siduri_migrations (name, checksum) VALUES ($1, $2)', [migration.name, migration.checksum]);
+                    await client.query('COMMIT');
+                    appliedList.push(migration.name);
+                }
+                catch (err) {
+                    await client.query('ROLLBACK');
+                    throw err;
+                }
+            }
+        }
+        const redacted = redactDatabaseUrl(connectionString);
+        const message = appliedList.length > 0
+            ? `Applied ${appliedList.length} migration(s) to ${redacted}`
+            : `Database schema up to date on ${redacted}`;
+        return {
+            status: appliedList.length > 0 ? 'APPLIED' : 'UP_TO_DATE',
+            appliedMigrations: appliedList,
+            skippedMigrations: skippedList,
+            message,
+        };
+    }
+    finally {
+        client.release();
+        await pool.end().catch(() => { });
+    }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,13 @@
+import { OrganManifest } from './manifest';
+export declare class OrganRegistry {
+    private manifests;
+    constructor(manifests?: OrganManifest[]);
+    register(manifest: OrganManifest): void;
+    get(organType: string): OrganManifest | undefined;
+    getAll(): OrganManifest[];
+    getAvailableOrganTypes(): string[];
+    /**
+     * Discover installed or monorepo organ packages.
+     */
+    static discover(searchRoots?: string[]): OrganRegistry;
+}

package/dist/discovery.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrganRegistry = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const manifest_1 = require("./manifest");
+class OrganRegistry {
+    manifests = new Map();
+    constructor(manifests) {
+        if (manifests) {
+            for (const m of manifests) {
+                this.manifests.set(m.organType, m);
+            }
+        }
+    }
+    register(manifest) {
+        const validated = (0, manifest_1.validateOrganManifest)(manifest);
+        this.manifests.set(validated.organType, validated);
+    }
+    get(organType) {
+        return this.manifests.get(organType);
+    }
+    getAll() {
+        return Array.from(this.manifests.values());
+    }
+    getAvailableOrganTypes() {
+        return Array.from(this.manifests.keys());
+    }
+    /**
+     * Discover installed or monorepo organ packages.
+     */
+    static discover(searchRoots) {
+        const registry = new OrganRegistry();
+        const rootsToScan = searchRoots && searchRoots.length > 0
+            ? searchRoots
+            : [
+                // 1. Monorepo organs folder relative to cli
+                node_path_1.default.resolve(__dirname, '../../packages/organs'),
+                // 2. Monorepo organs folder relative to cwd
+                node_path_1.default.resolve(process.cwd(), 'packages/organs'),
+                // 3. Node modules of current directory or global resolution
+                node_path_1.default.resolve(process.cwd(), 'node_modules/@siduri-x'),
+                node_path_1.default.resolve(__dirname, '../node_modules/@siduri-x'),
+            ];
+        const visitedDirs = new Set();
+        for (const root of rootsToScan) {
+            if (!node_fs_1.default.existsSync(root) || visitedDirs.has(root))
+                continue;
+            visitedDirs.add(root);
+            try {
+                const entries = node_fs_1.default.readdirSync(root, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const candidateDir = node_path_1.default.join(root, entry.name);
+                    const manifestPath = node_path_1.default.join(candidateDir, 'organ-manifest.json');
+                    if (node_fs_1.default.existsSync(manifestPath)) {
+                        try {
+                            const raw = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf8'));
+                            const manifest = (0, manifest_1.validateOrganManifest)(raw, manifestPath);
+                            registry.register(manifest);
+                        }
+                        catch (err) {
+                            console.warn(`[Siduri CLI] Warning: failed to parse manifest at ${manifestPath}: ${err.message}`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // Continue scanning other roots
+            }
+        }
+        return registry;
+    }
+}
+exports.OrganRegistry = OrganRegistry;

package/dist/discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/discovery.test.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const discovery_1 = require("./discovery");
+const generator_1 = require("./generator");
+describe('Discovery & Dynamic Composition System Tests (Phase 3)', () => {
+    const rootOrgansDir = node_path_1.default.resolve(__dirname, '../../packages/organs');
+    test('Registry successfully discovers all 10 organ packages from workspace', () => {
+        const registry = discovery_1.OrganRegistry.discover([rootOrgansDir]);
+        const manifests = registry.getAll();
+        expect(manifests.length).toBe(10);
+        const organTypes = registry.getAvailableOrganTypes().sort();
+        expect(organTypes).toEqual([
+            'behavior',
+            'body',
+            'brain',
+            'ear',
+            'hands',
+            'knowledge',
+            'memory',
+            'observation',
+            'vision',
+            'voice',
+        ]);
+    });
+    test('Generates valid instances from discovered manifests', () => {
+        const registry = discovery_1.OrganRegistry.discover([rootOrgansDir]);
+        // Test Brain + Hands + Vision
+        const brain = registry.get('brain');
+        const hands = registry.get('hands');
+        const vision = registry.get('vision');
+        const files = (0, generator_1.generateInstanceFiles)({
+            name: 'robotics-agent',
+            selectedManifests: [brain, hands, vision],
+        });
+        const pkg = JSON.parse(files['package.json']);
+        expect(Object.keys(pkg.dependencies).sort()).toEqual([
+            '@siduri-x/brain',
+            '@siduri-x/core',
+            '@siduri-x/hands',
+            '@siduri-x/vision',
+        ]);
+        const schema = JSON.parse(files['siduri.schema.json']);
+        expect(Object.keys(schema.properties.organs.properties).sort()).toEqual(['brain', 'hands', 'vision']);
+        const config = JSON.parse(files['siduri.config.json']);
+        expect(Object.keys(config.organs).sort()).toEqual(['brain', 'hands', 'vision']);
+        expect(files['.env.example']).toContain('OPENROUTER_API_KEY');
+        expect(files['.env.example']).toContain('ACTION_POLICY_SECRET');
+        expect(files['.env.example']).not.toContain('DATABASE_URL');
+    });
+    test('Validates manifest contract integrity during discovery', () => {
+        expect(() => {
+            const invalidRegistry = new discovery_1.OrganRegistry();
+            invalidRegistry.register({});
+        }).toThrow(/Invalid manifest/);
+    });
+});