@feltdb/core 0.7.3 → 0.8.0

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { getClient } from './api-client.js';
 import { loadFeltDBConfig, createDefaultConfig, validateModel, } from './config.js';
-const VERSION = '0.7.3';
+const VERSION = '0.8.0';
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,

package/dist/cli/managed-environment.js

@@ -0,0 +1,6 @@
+export function resolveManagedAuthorityEnvironment(environment) {
+    environment.VITE_FELTDB_URL || (environment.VITE_FELTDB_URL = environment.VITE_FELTDB_MANAGED_URL);
+    if (!environment.VITE_FELTDB_URL) {
+        throw new Error('Managed runtime requires VITE_FELTDB_MANAGED_URL in .env.local. Re-run managed setup or add your managed connection.');
+    }
+}

package/dist/cli/managed-project.js

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function readManagedProjectState(cwd = process.cwd()) {
+    const file = path.join(cwd, '.feltdb', 'managed.json');
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+}

package/dist/cli/proposal-client.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseFlowSpec } from '@feltdb/core';
+export function developmentProposalConnection(cwd = process.cwd()) {
+    const file = path.join(cwd, '.feltdb', 'connections.json');
+    const stored = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')).developmentAuthority : undefined;
+    const endpoint = process.env.VITE_FELTDB_URL || process.env.VITE_FELTDB_MANAGED_URL || stored?.endpoint;
+    if (!endpoint)
+        throw new Error('No running FeltDB proposal service. Start feltdb dev.');
+    const config = fs.existsSync(path.join(cwd, 'feltdb.config.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, 'feltdb.config.json'), 'utf8')) : {};
+    const published = fs.existsSync(path.join(cwd, '.feltdb', 'last-published.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'last-published.json'), 'utf8')) : {};
+    const managed = fs.existsSync(path.join(cwd, '.feltdb', 'managed.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'managed.json'), 'utf8')) : {};
+    const flowApplication = fs.existsSync(path.join(cwd, 'feltdb.flow')) ? parseFlowSpec(fs.readFileSync(path.join(cwd, 'feltdb.flow'), 'utf8')).app : undefined;
+    return { endpoint: endpoint.replace(/\/$/, ''), proposalAuthorityToken: stored?.proposalAuthorityToken,
+        applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managed.applicationId || published.applicationId || config.applicationId || flowApplication,
+        environment: managed.environment || published.environment || 'local' };
+}
+export class ProposalServiceClient {
+    constructor(connection, token = process.env.FELTDB_MANAGED_CONTROL_API_KEY || '') {
+        this.connection = connection;
+        this.token = token;
+    }
+    async request(pathname, init = {}) {
+        const response = await fetch(`${this.connection.endpoint}${pathname}`, { ...init, headers: {
+                ...(init.body ? { 'content-type': 'application/json' } : {}), ...(this.token ? { authorization: `Bearer ${this.token}` } : {}), ...init.headers,
+            } });
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok)
+            throw new Error(body.error || body.message || `Proposal service failed (${response.status})`);
+        return body;
+    }
+    scoped(pathname) {
+        const query = new URLSearchParams();
+        if (this.connection.applicationId)
+            query.set('application_id', this.connection.applicationId);
+        if (this.connection.environment)
+            query.set('environment', this.connection.environment);
+        return `${pathname}?${query}`;
+    }
+    actor(input = {}) { return { application_id: this.connection.applicationId, environment: this.connection.environment, ...input }; }
+    create(input) { return this.request('/v1/proposals', { method: 'POST', body: JSON.stringify(input) }); }
+    list(filters = {}) { const query = new URLSearchParams(); if (this.connection.applicationId)
+        query.set('application_id', this.connection.applicationId); query.set('environment', filters.environment || this.connection.environment || 'local'); if (filters.status)
+        query.set('status', filters.status); if (filters.limit)
+        query.set('limit', String(filters.limit)); if (filters.cursor)
+        query.set('cursor', filters.cursor); return this.request(`/v1/proposals?${query}`); }
+    get(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}`)); }
+    history(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/history`)); }
+    status(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/status`)); }
+    validate(id, actor = 'local-developer', proposedManifest) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/validate`, { method: 'POST', body: JSON.stringify(this.actor({ actor, proposed_manifest: proposedManifest })) }); }
+    preview(id, actor = 'local-developer') { return this.request(`/v1/proposals/${encodeURIComponent(id)}/preview`, { method: 'POST', body: JSON.stringify(this.actor({ actor })) }); }
+    getPreview(id) { return this.request(this.scoped(`/v1/previews/${encodeURIComponent(id)}`)); }
+    approve(id, actor = 'local-developer', approveAuthorization = false) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/approve`, { method: 'POST', body: JSON.stringify(this.actor({ actor, approve_authorization: approveAuthorization })) }); }
+    reject(id, actor = 'local-developer', reason) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/reject`, { method: 'POST', body: JSON.stringify(this.actor({ actor, reason })) }); }
+    transition(id, status, actor = 'local-developer', repositoryAuthority = false, approveAuthorization = false) {
+        return this.request(`/v1/proposals/${encodeURIComponent(id)}/status`, { method: 'PATCH', headers: repositoryAuthority && this.connection.proposalAuthorityToken
+                ? { 'FeltDB-Proposal-Authority': this.connection.proposalAuthorityToken, 'FeltDB-Repository-Apply': '1' } : {}, body: JSON.stringify(this.actor({ status, actor, approve_authorization: approveAuthorization })) });
+    }
+}
+export function proposalService(cwd = process.cwd(), endpoint) {
+    const connection = developmentProposalConnection(cwd);
+    return new ProposalServiceClient(endpoint ? { ...connection, endpoint } : connection);
+}

package/dist/cli/publish-engine.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { ApplicationManifestClient, canonicalApplicationBytes, flowSpecToManifest, parseFlowSpec, validateFlowSpec } from '@feltdb/core';
+function sha256(value) { return createHash('sha256').update(value).digest('hex'); }
+function loadEnv(file) {
+    const values = {};
+    if (!fs.existsSync(file))
+        return values;
+    for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const separator = line.indexOf('=');
+        if (separator < 1)
+            continue;
+        values[line.slice(0, separator).trim()] = line.slice(separator + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return values;
+}
+export function discoverPublishConfiguration(cwd = process.cwd(), environmentOverride) {
+    const configFile = path.join(cwd, 'feltdb.config.json');
+    if (!fs.existsSync(configFile))
+        throw new Error('feltdb.config.json is required for publish');
+    const project = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    const file = loadEnv(path.join(cwd, '.env.local'));
+    const managedFile = path.join(cwd, '.feltdb', 'managed.json');
+    const managed = fs.existsSync(managedFile) ? JSON.parse(fs.readFileSync(managedFile, 'utf8')) : {};
+    const value = (name) => process.env[name] || file[name];
+    const configuration = {
+        url: value('VITE_FELTDB_MANAGED_URL') || managed.url, token: value('FELTDB_MANAGED_CONTROL_API_KEY'),
+        tenantId: managed.tenantId || value('VITE_FELTDB_MANAGED_TENANT_ID'), applicationId: value('VITE_FELTDB_MANAGED_APPLICATION_ID') || managed.applicationId,
+        namespace: managed.namespace || value('VITE_FELTDB_MANAGED_NAMESPACE') || project.namespace,
+        environment: environmentOverride || managed.environment || value('VITE_FELTDB_MANAGED_ENVIRONMENT') || 'production',
+    };
+    const missing = Object.entries(configuration).filter(([, value]) => !value).map(([name]) => name);
+    if (missing.length)
+        throw new Error(`Managed publish configuration is incomplete in .env.local: ${missing.join(', ')}`);
+    return configuration;
+}
+function filesBelow(root, directory) {
+    const target = path.join(root, directory);
+    if (!fs.existsSync(target))
+        return [];
+    return fs.readdirSync(target, { withFileTypes: true }).flatMap(entry => {
+        const relative = path.join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            throw new Error(`Publish artifacts cannot be symbolic links: ${relative}`);
+        return entry.isDirectory() ? filesBelow(root, relative) : entry.isFile() ? [relative] : [];
+    });
+}
+export function buildPublishBundle(cwd, configuration) {
+    const flowPath = path.join(cwd, 'feltdb.flow');
+    if (!fs.existsSync(flowPath))
+        throw new Error('feltdb.flow is required for publish');
+    const flowSource = fs.readFileSync(flowPath, 'utf8');
+    const spec = parseFlowSpec(flowSource);
+    const diagnostics = validateFlowSpec(spec).filter(value => value.severity === 'error');
+    if (diagnostics.length)
+        throw new Error(`Publish validation failed: ${diagnostics.map(value => value.message).join('; ')}`);
+    const deployable = ['feltdb.flow', ...['workflows', 'agents', 'capabilities'].flatMap(directory => filesBelow(cwd, directory))].sort();
+    const artifacts = deployable.map(relative => {
+        const content = Buffer.from(fs.readFileSync(path.join(cwd, relative)));
+        const mediaType = relative.endsWith('.flow') ? 'text/x-feltdb-flow' : relative.endsWith('.json') ? 'application/json' : relative.endsWith('.ts') ? 'text/typescript' : 'text/plain';
+        return { path: relative.split(path.sep).join('/'), hash: `sha256:${sha256(content)}`, bytes: content.byteLength, mediaType, content: content.toString('base64') };
+    });
+    const artifactHash = `sha256:${sha256(artifacts.map(value => `${value.path}\0${value.hash}`).join('\n'))}`;
+    const manifest = flowSpecToManifest(spec, configuration.tenantId, configuration.applicationId);
+    const contractHash = (value) => `sha256:${sha256(Buffer.from(canonicalApplicationBytes(value)))}`;
+    manifest.metadata.labels = {
+        ...(manifest.metadata.labels || {}),
+        'feltdb.dsl_version': String(spec.version),
+        'feltdb.model_hash': contractHash({ collections: manifest.collections, indexes: manifest.indexes, references: manifest.references }),
+        'feltdb.authorization_hash': contractHash(manifest.policies),
+        'feltdb.workflow_hash': contractHash({ workflows: manifest.workflows, triggers: manifest.triggers, schedules: manifest.schedules }),
+        'feltdb.agent_hash': contractHash(manifest.agents),
+        'feltdb.capability_hash': contractHash(manifest.capabilities),
+        'feltdb.contract_hash': contractHash({ dsl_version: spec.version, manifest }),
+        'feltdb.flow_hash': `sha256:${sha256(flowSource.replace(/\r\n/g, '\n'))}`,
+        'feltdb.artifact_hash': artifactHash,
+        'feltdb.namespace': configuration.namespace,
+    };
+    manifest.artifacts = artifacts.map(value => ({ name: value.path, uri: `data:${value.mediaType};base64,${value.content}`, media_type: value.mediaType }));
+    const git = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const sourceRevision = git.status === 0 ? git.stdout.trim() : undefined;
+    if (sourceRevision)
+        manifest.metadata.labels['feltdb.source_revision'] = sourceRevision;
+    return { manifest, artifacts, artifactHash, sourceRevision };
+}
+function sameDefinition(left, right) {
+    return left.metadata.labels?.['feltdb.artifact_hash'] === right.metadata.labels?.['feltdb.artifact_hash'];
+}
+function activeRevision(revisions, pointers, environment) {
+    const id = pointers[environment];
+    return revisions.find(value => value.revision_id === id);
+}
+function describeChanges(current, bundle) {
+    if (!current)
+        return bundle.artifacts.map(value => `added     ${value.path}`);
+    const old = new Map(current.manifest.artifacts.map(value => [value.name, value.uri]));
+    const next = new Map(bundle.manifest.artifacts.map(value => [value.name, value.uri]));
+    return [...new Set([...old.keys(), ...next.keys()])].sort().flatMap(name => !old.has(name) ? [`added     ${name}`] : !next.has(name) ? [`removed   ${name}`] : old.get(name) !== next.get(name) ? [`modified  ${name}`] : []);
+}
+export async function publishApplication(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const log = options.log || console.log;
+    const configuration = discoverPublishConfiguration(cwd, options.environment);
+    const bundle = buildPublishBundle(cwd, configuration);
+    const client = new ApplicationManifestClient(configuration.url.replace(/\/$/, ''), configuration.token);
+    const cloud = await client.revisions(configuration.applicationId);
+    const current = activeRevision(cloud.revisions, cloud.environment_pointers, configuration.environment);
+    const changes = describeChanges(current, bundle);
+    log(options.dryRun ? 'FeltDB Publish Preview' : options.status ? 'FeltDB Publish Status' : 'FeltDB Publish');
+    log(`Application: ${bundle.manifest.metadata.name}`);
+    log(`Environment: ${configuration.environment}`);
+    log(`Namespace: ${configuration.namespace}`);
+    if (options.status) {
+        log(`Local: ${bundle.artifactHash}`);
+        log(`Cloud version: ${current?.revision_number ?? 'none'}`);
+        log(current && sameDefinition(current.manifest, bundle.manifest) ? 'Status: ✓ Synchronized' : 'Status: ↑ Changes ready to publish');
+        return { status: current && sameDefinition(current.manifest, bundle.manifest) ? 'synchronized' : 'changes', current, bundle };
+    }
+    if (current && sameDefinition(current.manifest, bundle.manifest)) {
+        log(`✓ Local application matches cloud version ${current.revision_number}.`);
+        log('Nothing to publish.');
+        return { status: 'unchanged', current, bundle };
+    }
+    log('Changes:');
+    changes.forEach(value => log(`  ${value}`));
+    if (!options.noBuild) {
+        const packageFile = path.join(cwd, 'package.json');
+        const packageManifest = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+        if (!packageManifest.scripts?.build)
+            throw new Error('package.json must define a build script for publish');
+        const result = spawnSync('npm', ['run', 'build'], { cwd, stdio: 'inherit' });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0)
+            throw new Error(`Application build failed with exit code ${result.status}`);
+    }
+    const draft = await client.createDraft(configuration.applicationId, current?.revision_id);
+    const updated = await client.updateDraft(configuration.applicationId, draft, bundle.manifest);
+    const validation = await client.validateDraft(configuration.applicationId, updated.draft_id);
+    if (!validation.valid)
+        throw new Error(`Publish validation failed. No cloud changes were activated. ${validation.issues.map(value => `${value.path}: ${value.message}`).join('; ')}`);
+    if (options.dryRun) {
+        log(`Validation: ✓ ${validation.compatibility}`);
+        log('No changes have been published.');
+        return { status: 'preview', current, bundle, validation };
+    }
+    if (!options.yes && !(await options.confirm?.('Publish these changes?')))
+        throw new Error('Publish cancelled');
+    const revision = await client.commitDraft(configuration.applicationId, updated.draft_id);
+    const diff = await client.diff(configuration.applicationId, revision.revision_id, current?.revision_id);
+    if ((diff.classification === 'BREAKING' || diff.classification === 'MIGRATION_REQUIRED' || diff.security_changes.length) && !options.approveDestructive) {
+        throw new Error(`Publish requires explicit approval before activation (${diff.classification}${diff.security_changes.length ? ', authorization boundary changed' : ''}). Immutable version ${revision.revision_number} was staged but the active cloud version was not changed.`);
+    }
+    const promoted = await client.promoteEnvironment(configuration.applicationId, configuration.environment, revision.revision_id, current?.revision_id, options.message || 'Published from feltdb CLI', Boolean(options.approveDestructive));
+    fs.mkdirSync(path.join(cwd, '.feltdb'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.feltdb', 'last-published.json'), `${JSON.stringify({ applicationId: configuration.applicationId, tenantId: configuration.tenantId, namespace: configuration.namespace, environment: configuration.environment, version: revision.revision_number, revisionId: revision.revision_id, contractHash: bundle.manifest.metadata.labels?.['feltdb.contract_hash'], artifactHash: bundle.artifactHash, sourceRevision: bundle.sourceRevision, publishedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+    log(`✓ Published immutable version ${revision.revision_number}`);
+    log(`✓ Activated in ${configuration.environment}`);
+    return { status: 'published', current, bundle, revision, diff, promoted };
+}

package/dist/cli/source-sync.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { compileApplicationContract, createContractSnapshot, flowSourceHash, validateFlowProposal, } from '@feltdb/core';
+import { parseFlowSpec } from '@feltdb/core';
+const FLOW_FILE = 'feltdb.flow';
+const GENERATED_FILE = 'src/feltdb/generated-contract.ts';
+const SYNC_STATE = '.feltdb/source-sync.json';
+function digest(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function readJson(file) {
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : undefined;
+}
+function gitDirty(cwd, files) {
+    const result = spawnSync('git', ['status', '--porcelain', '--', ...files], { cwd, encoding: 'utf8' });
+    if (result.status !== 0)
+        return [];
+    return result.stdout.split(/\r?\n/).filter(Boolean).map(line => line.slice(3));
+}
+export async function repositoryContext(cwd = process.cwd(), plannedFiles = [FLOW_FILE, GENERATED_FILE]) {
+    const git = (args) => spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const rootResult = git(['rev-parse', '--show-toplevel']);
+    const root = rootResult.status === 0 ? rootResult.stdout.trim() : path.resolve(cwd);
+    const branchResult = git(['branch', '--show-current']);
+    const commitResult = git(['rev-parse', 'HEAD']);
+    const context = await loadLocalDevelopmentContract(root);
+    return { root, branch: branchResult.status === 0 ? branchResult.stdout.trim() || undefined : undefined,
+        commit: commitResult.status === 0 ? commitResult.stdout.trim() : undefined, dirty: gitDirty(root, plannedFiles),
+        flowPath: path.join(root, FLOW_FILE), flowHash: context.flowHash };
+}
+export function assertProposalSourcePlan(sourcePlan) {
+    const allowed = new Set([FLOW_FILE, GENERATED_FILE]);
+    if (!sourcePlan?.files?.length)
+        throw new Error('SOURCE_PLAN_BLOCKED: Proposal has no source operations');
+    for (const operation of sourcePlan.files) {
+        if (!allowed.has(operation.path) || !['add', 'modify'].includes(operation.operation))
+            throw new Error(`SOURCE_PLAN_BLOCKED: unsupported ${operation.operation} operation for ${operation.path}`);
+    }
+    if (!sourcePlan.files.some(value => value.path === FLOW_FILE))
+        throw new Error(`SOURCE_PLAN_BLOCKED: ${FLOW_FILE} synchronization is required`);
+}
+export async function loadLocalDevelopmentContract(cwd = process.cwd()) {
+    const flowPath = path.join(cwd, FLOW_FILE);
+    if (!fs.existsSync(flowPath))
+        throw new Error(`${FLOW_FILE} is required`);
+    const source = fs.readFileSync(flowPath, 'utf8');
+    const project = readJson(path.join(cwd, 'feltdb.config.json')) ?? {};
+    const managed = readJson(path.join(cwd, '.feltdb', 'managed.json')) ?? {};
+    const published = readJson(path.join(cwd, '.feltdb', 'last-published.json'));
+    const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID
+        || managed.applicationId || published?.applicationId || project.applicationId || parseFlowSpec(source).app;
+    const tenantId = managed.tenantId || published?.tenantId || 'local';
+    const environment = managed.environment || published?.environment || 'local';
+    const contract = await compileApplicationContract(parseFlowSpec(source), tenantId, applicationId);
+    return {
+        source,
+        flowHash: await flowSourceHash(source),
+        snapshot: createContractSnapshot(contract, {
+            environment,
+            contractVersion: published?.version ?? 1,
+        }),
+    };
+}
+export async function reviewFlowProposal(proposal, cwd = process.cwd()) {
+    const current = await loadLocalDevelopmentContract(cwd);
+    return validateFlowProposal({ proposal, currentFlow: current.source, snapshot: current.snapshot });
+}
+function generatedContractSource(review) {
+    const snapshot = createContractSnapshot(review.proposedContract, {
+        environment: 'local',
+        contractVersion: review.proposal.baseContractHash === review.proposedContract.hashes.application ? 1 : 2,
+    });
+    const collections = review.proposedSpec.collections.map(collection => ({
+        name: collection.name,
+        fields: collection.fields.map(field => ({ name: field.name, type: field.type, optional: field.optional })),
+    }));
+    const typeName = (value) => {
+        const cleaned = value.replace(/[^A-Za-z0-9_$]/g, '_');
+        return /^[A-Za-z_$]/.test(cleaned) ? cleaned : `_${cleaned}`;
+    };
+    const valueType = (value) => {
+        const normalized = value.toLowerCase().replace(/\?$/, '');
+        if (['int', 'integer', 'float', 'number'].includes(normalized))
+            return 'number';
+        if (['bool', 'boolean'].includes(normalized))
+            return 'boolean';
+        if (['json', 'object'].includes(normalized))
+            return 'unknown';
+        if (normalized.endsWith('[]'))
+            return `${valueType(normalized.slice(0, -2))}[]`;
+        return 'string';
+    };
+    const types = review.proposedSpec.collections.map(collection => {
+        const fields = collection.fields.map(field => `  ${JSON.stringify(field.name)}${field.optional ? '?' : ''}: ${valueType(field.type)};`);
+        return `export interface ${typeName(collection.name)}Record {\n  id: string;\n${fields.join('\n')}\n}`;
+    }).join('\n\n');
+    const bindings = review.proposedSpec.collections.map(collection => `  ${JSON.stringify(collection.name)}: database.collection<${typeName(collection.name)}Record>(${JSON.stringify(collection.name)}),`).join('\n');
+    return `/* Generated by feltdb sync from feltdb.flow. Do not edit this file directly. */\n`
+        + `export const FELTDB_CONTRACT = ${JSON.stringify(snapshot, null, 2)} as const;\n\n`
+        + `export const FELTDB_COLLECTIONS = ${JSON.stringify(collections, null, 2)} as const;\n\n`
+        + `${types}\n\n`
+        + `export interface FeltDBCollectionBinder {\n  collection<T>(name: string): unknown;\n}\n\n`
+        + `/** Bind the generated, typed collection map to the project's FeltDB instance. */\n`
+        + `export function bindGeneratedCollections(database: FeltDBCollectionBinder) {\n  return {\n${bindings}\n  };\n}\n`;
+}
+export function syncGeneratedSource(review, cwd = process.cwd(), options = {}) {
+    const target = path.join(cwd, GENERATED_FILE);
+    const statePath = path.join(cwd, SYNC_STATE);
+    const state = readJson(statePath) ?? { files: {} };
+    if (fs.existsSync(target)) {
+        const actual = digest(fs.readFileSync(target));
+        const recorded = state.files?.[GENERATED_FILE];
+        if ((!recorded || recorded !== actual) && !options.replace) {
+            throw new Error(`SOURCE_SYNC_CONFLICT: ${GENERATED_FILE} has developer changes; review it or rerun with --replace-generated`);
+        }
+    }
+    const source = generatedContractSource(review);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, source);
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, `${JSON.stringify({ version: 1, contractHash: review.proposedContract.hashes.application, files: { [GENERATED_FILE]: digest(source) } }, null, 2)}\n`, { mode: 0o600 });
+    return { written: [GENERATED_FILE] };
+}
+function assertGeneratedSourceSafe(cwd, replace = false) {
+    const target = path.join(cwd, GENERATED_FILE);
+    if (!fs.existsSync(target) || replace)
+        return;
+    const state = readJson(path.join(cwd, SYNC_STATE));
+    const recorded = state?.files?.[GENERATED_FILE];
+    if (!recorded || recorded !== digest(fs.readFileSync(target))) {
+        throw new Error(`SOURCE_SYNC_CONFLICT: ${GENERATED_FILE} has developer changes; review it or rerun with --replace-generated`);
+    }
+}
+export async function applyFlowProposal(proposal, cwd = process.cwd(), options = {}) {
+    const review = await reviewFlowProposal(proposal, cwd);
+    const dirty = gitDirty(cwd, [FLOW_FILE, GENERATED_FILE]);
+    if (dirty.length && !options.allowDirty)
+        throw new Error(`DIRTY_SOURCE: uncommitted changes affect ${dirty.join(', ')}`);
+    if (review.authorizationChanges.length && !options.approveAuthorization) {
+        throw new Error(`AUTHORIZATION_APPROVAL_REQUIRED: ${review.authorizationChanges.map(change => change.policy).join(', ')}`);
+    }
+    if (options.syncSource !== false)
+        assertGeneratedSourceSafe(cwd, options.replaceGenerated);
+    fs.writeFileSync(path.join(cwd, FLOW_FILE), proposal.proposedFlow.replace(/\r\n/g, '\n'));
+    const synchronized = options.syncSource === false ? { written: [] } : syncGeneratedSource(review, cwd, { replace: options.replaceGenerated });
+    return { ...review, written: [FLOW_FILE, ...synchronized.written] };
+}
+/** Apply and verify as one developer-visible transaction, restoring exact prior bytes on failure. */
+export async function applyFlowProposalAtomic(proposal, cwd = process.cwd(), options = {}) {
+    const files = [FLOW_FILE, GENERATED_FILE, SYNC_STATE].map(relative => ({ relative, absolute: path.join(cwd, relative) }));
+    const before = files.map(file => ({ ...file, existed: fs.existsSync(file.absolute), bytes: fs.existsSync(file.absolute) ? fs.readFileSync(file.absolute) : undefined }));
+    try {
+        const result = await applyFlowProposal(proposal, cwd, options);
+        options.verify?.();
+        return result;
+    }
+    catch (error) {
+        for (const file of before) {
+            if (file.existed && file.bytes) {
+                fs.mkdirSync(path.dirname(file.absolute), { recursive: true });
+                fs.writeFileSync(file.absolute, file.bytes);
+            }
+            else if (fs.existsSync(file.absolute))
+                fs.rmSync(file.absolute, { force: true });
+        }
+        throw error;
+    }
+}
+export function describeProposal(review) {
+    return [
+        ...review.diff.added.map(value => `+ ${value}`),
+        ...review.diff.changed.map(value => `~ ${value}`),
+        ...review.diff.removed.map(value => `- ${value}`),
+        ...review.authorizationChanges.flatMap(value => [
+            `AUTHORIZATION CHANGE${value.widening ? ' (possible widening)' : ''}: ${value.policy}`,
+            `  before: ${(value.before ?? ['<absent>']).join(' | ')}`,
+            `  after:  ${(value.after ?? ['<removed>']).join(' | ')}`,
+        ]),
+        ...review.migration.filter(value => value.safety !== 'safe').map(value => `${value.safety.toUpperCase()}: ${value.target} — ${value.detail}`),
+    ];
+}

package/dist/create/cli.js

@@ -10,7 +10,7 @@ import readline from 'readline';
 import { spawn, spawnSync } from 'child_process';
 import { createProject } from './create.js';
 import { FELTDB_PACKAGE_VERSION } from './package-versions.js';
-import { configureManagedAccount } from './managed-account.js';
+import { configureManagedAccount, finalizeManagedProvisioning } from './managed-account.js';
 import { localFeltdbExecutable } from './development-handoff.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function parseArgs(args) {
@@ -308,7 +308,7 @@ Learn more: https://github.com/rkendel1/feltdb`);
         await createProject({
             projectName,
             autoYes: shouldAutoYes,
-            templatesDir: path.join(__dirname, '../template'),
+            templatesDir: path.join(__dirname, 'template'),
             runtime: options.runtime,
             framework: options.framework,
             distributed: options.distributed,
@@ -331,9 +331,18 @@ Learn more: https://github.com/rkendel1/feltdb`);
         }
         console.log('\n✅ FeltDB application created successfully!\n');
         const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        if (options.runtime === 'managed' && !shouldInstall) {
+            throw new Error('Managed provisioning requires dependency installation so the initial revision can be built, published, promoted, and verified. Remove --no-install.');
+        }
         if (shouldInstall) {
             console.log(`📦 Installing application, Studio${options.webllm ? ', and local WebLLM app builder' : ''} dependencies...\n`);
             await run(npm, ['install'], projectDir);
+            if (options.runtime === 'managed') {
+                console.log('\n☁️  Publishing and verifying the initial managed revision...\n');
+                await run(localFeltdbExecutable(projectDir), ['publish', '--yes', '--approve-destructive-changes'], projectDir);
+                const finalized = await finalizeManagedProvisioning({ projectDir });
+                console.log(`✓ Managed runtime verified at revision ${finalized.revisionId}`);
+            }
         }
         if (shouldStart) {
             if (!shouldInstall) {

package/dist/create/create.js

@@ -49,9 +49,12 @@ export async function createProject(options) {
             test: 'node --test',
             feltdb: 'feltdb',
             'feltdb:server': 'feltdb server',
-            'feltdb:connect': 'feltdb connect http://localhost:7700',
+            'feltdb:connect': 'feltdb connect',
             'feltdb:status': 'feltdb status',
             'feltdb:studio': 'feltdb studio',
+            'feltdb:publish': 'feltdb publish',
+            'feltdb:ai': 'feltdb ai',
+            'feltdb:sync': 'feltdb sync',
             'feltdb:validate': 'feltdb validate',
             'feltdb:diff': 'feltdb diff',
             'feltdb:deploy': 'feltdb deploy',
@@ -176,25 +179,26 @@ ${hasAgents ? `  agent WorkspaceAssistant {
             lib: ['ES2020', 'DOM'],
             declaration: true,
             outDir: './dist',
-            rootDir: './src',
+            rootDir: '.',
             strict: true,
             esModuleInterop: true,
             skipLibCheck: true,
             forceConsistentCasingInFileNames: true,
-            moduleResolution: 'node',
+            moduleResolution: 'bundler',
         },
-        include: ['src/**/*'],
+        include: framework === 'react' ? ['src/**/*', 'agents/**/*', 'capabilities/**/*', 'workflows/**/*'] : ['src/**/*'],
         exclude: ['node_modules'],
     };
     if (framework === 'react') {
         tsconfig.compilerOptions.jsx = 'react-jsx';
+        tsconfig.compilerOptions.types = ['vite/client'];
     }
     fs.writeFileSync(path.join(projectDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2));
     // Create main application files
     const runtimeOptions = runtime === 'browser'
         ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', browser: true }"
         : runtime === 'managed'
-            ? "{ namespace: import.meta.env.VITE_FELTDB_MANAGED_NAMESPACE || import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || import.meta.env.VITE_FELTDB_URL || '', token: import.meta.env.VITE_FELTDB_MANAGED_API_KEY || import.meta.env.VITE_FELTDB_API_KEY || '' } }"
+            ? "{ namespace: '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_MANAGED_URL || '', applicationId: import.meta.env.VITE_FELTDB_MANAGED_APPLICATION_ID, environment: 'production' } }"
             : runtime === 'self-hosted'
                 ? "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', server: { url: import.meta.env.VITE_FELTDB_URL || 'http://localhost:7700', token: import.meta.env.VITE_FELTDB_API_KEY || '' } }"
                 : "{ namespace: import.meta.env.VITE_FELTDB_NAMESPACE || '" + applicationName + "', memory: true }";
@@ -365,7 +369,7 @@ async function logActivity(event: Omit<ActivityEvent, 'id' | 'timestamp'>): Prom
 `;
     fs.writeFileSync(path.join(srcDir, 'feltdb.ts'), feltdbTs);
     // Create a real local-inference agent for browser projects.
-    if (hasAgents && hasWebLLM) {
+    if (hasAgents && hasWebLLM && framework !== 'react') {
         const agentTs = `import { WebLLMProvider } from '@feltdb/webllm';
 import { db, reports } from '../../src/feltdb';
 
@@ -1185,6 +1189,17 @@ root.render(
 );
 `;
         fs.writeFileSync(path.join(srcDir, 'index.tsx'), indexTsx);
+        const canonicalTemplate = path.join(templatesDir, 'default-project');
+        if (fs.existsSync(canonicalTemplate)) {
+            fs.cpSync(path.join(canonicalTemplate, 'src'), srcDir, { recursive: true });
+            for (const directory of ['agents', 'capabilities', 'workflows']) {
+                fs.cpSync(path.join(canonicalTemplate, directory), path.join(projectDir, directory), { recursive: true });
+                fs.rmSync(path.join(feltdbDir, directory), { recursive: true, force: true });
+            }
+            fs.writeFileSync(path.join(projectDir, 'feltdb.flow'), fs.readFileSync(path.join(canonicalTemplate, 'feltdb.flow'), 'utf8').replace('app FeltDBStarter', `app ${appName}`));
+            const databasePath = path.join(srcDir, 'feltdb.ts');
+            fs.writeFileSync(databasePath, fs.readFileSync(databasePath, 'utf8').replace(/export const managedRuntime[\s\S]*?\n\} : \{ namespace: import\.meta\.env\.VITE_FELTDB_NAMESPACE \|\| 'feltdb-starter', browser: true \}\);/, `export const managedRuntime = ${runtime === 'managed'};\nexport const db = createFeltDB(${runtimeOptions});`));
+        }
     }
     else {
         // Create vanilla JS app
@@ -1219,8 +1234,7 @@ main().catch(console.error);
     const envExample = `# FeltDB Configuration
 # Copy this file to .env.local and update the values
 
-# API Key for authenticating with FeltDB servers
-# Leave empty for browser runtime; required for authenticated self-hosted and managed runtimes
+# API key for authenticated self-hosted browser access
 VITE_FELTDB_API_KEY=
 
 # FeltDB Server URL (self-hosted or managed runtime)
@@ -1228,11 +1242,10 @@ VITE_FELTDB_URL=http://localhost:7700
 
 # Managed example: https://runtime.your-app.feltdb.com
 VITE_FELTDB_MANAGED_URL=
-VITE_FELTDB_MANAGED_API_KEY=
-VITE_FELTDB_MANAGED_TENANT_ID=
 VITE_FELTDB_MANAGED_APPLICATION_ID=
-VITE_FELTDB_MANAGED_NAMESPACE=
-VITE_FELTDB_MANAGED_ENVIRONMENT=production
+# Server/control-plane only. Never rename with a VITE_ prefix.
+FELTDB_MANAGED_CONTROL_API_KEY=
+FELTDB_TOKEN=
 
 # Override the default self-hosted container image
 # By default the server image is built locally from the bundled source.
@@ -1371,7 +1384,7 @@ The self-hosted instance runs on \`http://localhost:7700\` by default.
 }
 \`\`\`
 
-Managed mode uses the same application API with a FeltDB-hosted endpoint. The CLI creates \`.env.local\` with \`VITE_FELTDB_MANAGED_URL\` and \`VITE_FELTDB_MANAGED_API_KEY\` after account setup. Studio uses that same connection for state, health, operations, and API-key administration.
+Managed mode uses the same application API with a FeltDB-hosted endpoint. The CLI writes only the public URL and application ID plus separate server-only publish and runtime credentials. Tenant, namespace, environment, and active revision are discovered deployment metadata under \`.feltdb/managed.json\`.
 
 ## Vector Search Status
 
@@ -1524,6 +1537,7 @@ build/
 *.log
 .DS_Store
 .feltdb/
+.feltdb-data/
 `;
     fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignore);
     // Create README
@@ -1639,7 +1653,7 @@ FeltDB runs through a dedicated server with Docker Compose and persistent data v
 
 ### Managed Runtime
 
-FeltDB provides the runtime endpoint, durable storage, synchronization, and background workload infrastructure. The CLI configures \`VITE_FELTDB_MANAGED_URL\` and \`VITE_FELTDB_MANAGED_API_KEY\` in \`.env.local\`.
+FeltDB provides the runtime endpoint, durable storage, synchronization, and background workload infrastructure. The CLI configures the public \`VITE_FELTDB_MANAGED_*\` identity, separate server-only control and data-plane credentials, and the promoted revision in \`.env.local\`. The browser API-key value stays empty because browser users receive short-lived actor sessions.
 
 ## Configuration
 
@@ -1669,12 +1683,14 @@ Create a \`.env.local\` file (copy from \`.env.example\`):
 \`\`\`
 VITE_FELTDB_API_KEY=your_api_key_here
 VITE_FELTDB_URL=http://localhost:7700
-VITE_FELTDB_MANAGED_API_KEY=your_managed_api_key_here
 VITE_FELTDB_MANAGED_URL=https://api.feltdb.com
+VITE_FELTDB_MANAGED_APPLICATION_ID=your_application_id
+FELTDB_MANAGED_CONTROL_API_KEY=your_server_only_control_key
+FELTDB_TOKEN=your_server_only_application_data_key
 VITE_FELTDB_WEBSOCKET_URL=ws://localhost:7700
 \`\`\`
 
-These are required when connecting to an authenticated self-hosted or managed FeltDB instance.
+Never expose \`FELTDB_MANAGED_CONTROL_API_KEY\` or \`FELTDB_TOKEN\` through a \`VITE_\` variable. Managed browser access uses \`db.auth.signUp()\` and \`db.auth.signIn()\`; the active revision is discovered rather than configured.
 
 ## Development
 
@@ -1795,6 +1811,12 @@ If port 5173 is in use:
 MIT
 `;
     fs.writeFileSync(path.join(projectDir, 'README.md'), readme);
+    if (framework === 'react') {
+        const canonicalReadme = path.join(templatesDir, 'default-project', 'README.md');
+        if (fs.existsSync(canonicalReadme)) {
+            fs.writeFileSync(path.join(projectDir, 'README.md'), fs.readFileSync(canonicalReadme, 'utf8').replace('# My FeltDB App', `# ${applicationName}`));
+        }
+    }
     // Initialize Development Workspace
     // This creates .feltdb/workspace.json which enables all FeltDB-aware tools
     // (CLI, IDE, agents, browser extensions) to discover and connect to the