@plumbus/core 0.1.0

package/dist/cli/commands/init.js

@@ -0,0 +1,261 @@
+// ── plumbus init ──
+// Generate AI agent wiring files that connect coding agents to framework knowledge
+import * as path from 'node:path';
+import { info, success, writeFile } from '../utils.js';
+const CORE_INSTRUCTION_TOPICS = [
+    'framework',
+    'cli',
+    'capabilities',
+    'flows',
+    'entities',
+    'events',
+    'ai',
+    'security',
+    'governance',
+    'testing',
+    'patterns',
+];
+const UI_INSTRUCTION_REFERENCES = [
+    {
+        area: 'frontend/ui generation',
+        path: 'node_modules/@plumbus/ui/instructions/framework.md',
+    },
+    {
+        area: 'typed clients and hooks',
+        path: 'node_modules/@plumbus/ui/instructions/client-generator.md',
+    },
+    {
+        area: 'auth helpers',
+        path: 'node_modules/@plumbus/ui/instructions/auth-generator.md',
+    },
+    {
+        area: 'form metadata generation',
+        path: 'node_modules/@plumbus/ui/instructions/form-generator.md',
+    },
+    {
+        area: 'Next.js frontend scaffolding',
+        path: 'node_modules/@plumbus/ui/instructions/nextjs-template.md',
+    },
+    {
+        area: 'frontend test coverage',
+        path: 'node_modules/@plumbus/ui/instructions/testing.md',
+    },
+    {
+        area: 'frontend generation patterns',
+        path: 'node_modules/@plumbus/ui/instructions/patterns.md',
+    },
+];
+function addInstructionReferenceLines(lines, inline) {
+    if (inline) {
+        lines.push('Refer to the bundled framework and UI instruction files in this project for full SDK documentation.');
+        return;
+    }
+    for (const topic of CORE_INSTRUCTION_TOPICS) {
+        lines.push(`- When working on ${topic}, read \`node_modules/@plumbus/core/instructions/${topic}.md\``);
+    }
+    for (const reference of UI_INSTRUCTION_REFERENCES) {
+        lines.push(`- When working on ${reference.area}, read \`${reference.path}\``);
+    }
+}
+/** Generate the copilot-instructions.md content */
+export function generateCopilotInstructions(inline) {
+    const lines = [
+        '# Plumbus Framework — Copilot Instructions',
+        '',
+        'This project is built with the Plumbus framework — an AI-native, contract-driven TypeScript framework.',
+        '',
+        '## Key Conventions',
+        '- Business logic lives in `app/capabilities/<domain>/<name>/`',
+        '- Data models in `app/entities/`',
+        '- Workflows in `app/flows/<domain>/<name>/`',
+        '- Events in `app/events/`',
+        '- AI prompts in `app/prompts/`',
+        '- Config in `config/`',
+        '',
+        '## Edit Zones',
+        '- **Safe**: `app/` directory (capabilities, entities, flows, events, prompts), `config/`, tests',
+        '- **Restricted**: `.plumbus/` generated files (regenerated by CLI)',
+        '- **Forbidden**: `node_modules/`, `dist/`',
+        '',
+        '## CLI Scaffolding',
+        '**Always run CLI commands from the project root**. Use the Plumbus CLI to scaffold new primitives and UI artifacts:',
+        '```',
+        'plumbus entity new <EntityName>',
+        'plumbus capability new <CapabilityName>',
+        'plumbus event new <EventName>',
+        'plumbus flow new <FlowName>',
+        'plumbus prompt new <PromptName>',
+        'plumbus ui generate',
+        'plumbus ui nextjs <output-dir>',
+        '```',
+        'After scaffolding, fill in the `// TODO` sections in the generated files.',
+        '',
+        '## SDK Reference',
+    ];
+    addInstructionReferenceLines(lines, inline);
+    lines.push('', '## Project Brief', 'See `.plumbus/briefs/project.md` for project-specific context.', '');
+    return lines.join('\n');
+}
+/** Generate the Cursor .mdc rule content */
+export function generateCursorRule(inline) {
+    const lines = [
+        '---',
+        'description: Plumbus framework conventions and SDK reference',
+        'globs: app/**',
+        '---',
+        '',
+        '# Plumbus Framework',
+        '',
+        'This project uses the Plumbus framework for building AI-native, contract-driven applications.',
+        '',
+        '## Conventions',
+        '- Capabilities: `app/capabilities/<domain>/<name>/`',
+        '- Entities: `app/entities/<name>.entity.ts`',
+        '- Flows: `app/flows/<domain>/<name>/`',
+        '- Events: `app/events/<name>.event.ts`',
+        '- Prompts: `app/prompts/<name>.prompt.ts`',
+        '',
+        '## Edit Zones',
+        '- Safe: `app/`, `config/`, tests',
+        '- Restricted: `.plumbus/generated/`',
+        '- Forbidden: `node_modules/`, `dist/`',
+        '',
+        '## SDK Reference',
+    ];
+    addInstructionReferenceLines(lines, inline);
+    lines.push('');
+    return lines.join('\n');
+}
+/** Generate capability-specific Cursor rule */
+export function generateCursorCapabilityRule() {
+    return `---
+description: Plumbus capability development rules
+globs: app/capabilities/**
+---
+
+When creating or modifying capabilities:
+- Use \`defineCapability()\` from @plumbus/core
+- Always declare effects (data, events, external, ai)
+- Set access policies (deny-by-default)
+- Use \`ctx.data\`, \`ctx.events\`, \`ctx.ai\` within handlers
+- Reference: \`node_modules/@plumbus/core/instructions/capabilities.md\`
+`;
+}
+/** Generate AGENTS.md content */
+export function generateAgentsMd(inline) {
+    const lines = [
+        '# AGENTS.md — Plumbus Framework',
+        '',
+        'This project is built with the Plumbus framework.',
+        '',
+        '## Architecture',
+        'AI-native, contract-driven TypeScript framework with primitives:',
+        'Entities, Capabilities, Flows, Events, Prompts — composed through `ctx`.',
+        '',
+        '## Directory Structure',
+        '- `app/capabilities/<domain>/<name>/` — Business logic',
+        '- `app/entities/` — Data models',
+        '- `app/flows/<domain>/<name>/` — Multi-step workflows',
+        '- `app/events/` — Domain events',
+        '- `app/prompts/` — AI prompt definitions',
+        '- `config/` — App + AI configuration',
+        '- `.plumbus/generated/` — Auto-generated (do not edit)',
+        '',
+        '## Edit Zones',
+        '- **Safe**: `app/`, `config/`, tests',
+        '- **Restricted**: `.plumbus/` (regenerated by `plumbus generate`)',
+        '- **Forbidden**: `node_modules/`, `dist/`',
+        '',
+        '## SDK Reference',
+    ];
+    addInstructionReferenceLines(lines, inline);
+    lines.push('');
+    return lines.join('\n');
+}
+/** Generate the project brief */
+export function generateProjectBrief() {
+    return `# Project Brief
+
+> Auto-generated by \`plumbus init\`. Update with \`plumbus agent sync\`.
+
+## Registered Resources
+
+- **Entities**: (run \`plumbus agent sync\` to populate)
+- **Capabilities**: (run \`plumbus agent sync\` to populate)
+- **Flows**: (run \`plumbus agent sync\` to populate)
+- **Events**: (run \`plumbus agent sync\` to populate)
+- **Prompts**: (run \`plumbus agent sync\` to populate)
+
+## Configuration
+
+- **Auth**: (detected at sync)
+- **AI**: (detected at sync)
+- **Compliance**: (detected at sync)
+
+## Governance Warnings
+
+None detected. Run \`plumbus verify\` to check.
+`;
+}
+/** Write all files for a given agent format */
+export function writeAgentFiles(projectRoot, formats, inline, includeProjectBrief = true) {
+    const written = [];
+    for (const format of formats) {
+        switch (format) {
+            case 'copilot': {
+                const filePath = path.join(projectRoot, '.github', 'copilot-instructions.md');
+                writeFile(filePath, generateCopilotInstructions(inline));
+                written.push('.github/copilot-instructions.md');
+                break;
+            }
+            case 'cursor': {
+                const mainRule = path.join(projectRoot, '.cursor', 'rules', 'plumbus.mdc');
+                writeFile(mainRule, generateCursorRule(inline));
+                written.push('.cursor/rules/plumbus.mdc');
+                const capRule = path.join(projectRoot, '.cursor', 'rules', 'plumbus-capabilities.mdc');
+                writeFile(capRule, generateCursorCapabilityRule());
+                written.push('.cursor/rules/plumbus-capabilities.mdc');
+                break;
+            }
+            case 'agents-md': {
+                const filePath = path.join(projectRoot, 'AGENTS.md');
+                writeFile(filePath, generateAgentsMd(inline));
+                written.push('AGENTS.md');
+                break;
+            }
+        }
+    }
+    if (includeProjectBrief) {
+        const briefPath = path.join(projectRoot, '.plumbus', 'briefs', 'project.md');
+        writeFile(briefPath, generateProjectBrief());
+        written.push('.plumbus/briefs/project.md');
+    }
+    return written;
+}
+function parseAgentFormats(agent) {
+    if (!agent || agent === 'all') {
+        return ['copilot', 'cursor', 'agents-md'];
+    }
+    const valid = ['copilot', 'cursor', 'agents-md'];
+    if (valid.includes(agent)) {
+        return [agent];
+    }
+    return ['copilot', 'cursor', 'agents-md'];
+}
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('Generate AI agent wiring files for the project')
+        .option('--agent <format>', 'Agent format: copilot, cursor, all (default: all)')
+        .option('--inline', 'Copy full instruction content instead of referencing node_modules')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        const formats = parseAgentFormats(opts.agent);
+        const written = writeAgentFiles(projectRoot, formats, opts.inline ?? false);
+        for (const f of written) {
+            success(`Created ${f}`);
+        }
+        info('Agent wiring complete. Run `plumbus agent sync` to populate project brief.');
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/init.js.map

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

package/dist/cli/commands/migrate.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+export interface MigrateOptions {
+    json?: boolean;
+}
+export declare function registerMigrateCommand(program: Command): void;
+export declare function registerDbCommand(program: Command): void;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/cli/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/migrate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAgED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4X7D;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwHxD"}