create-flowdular 0.2.3 → 0.2.5

package/agent-template/.ai/blueprints/release/allowed-paths.yaml

@@ -0,0 +1,19 @@
+schemaVersion: 1
+write: []
+deny:
+  - '**'
+notes:
+  - a release commits what the CLI produced; nothing is edited by hand
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install

package/agent-template/.ai/blueprints/release/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "release",
+	"version": "1.0.0",
+	"risk": "process",
+	"agentRoles": ["module-executor"],
+	"executorProfiles": ["repo-agent"],
+	"requiredReviewers": ["reviewer", "platform-owner"],
+	"requiresApprovedSpec": false
+}

package/agent-template/.ai/blueprints/release/examples/invalid/input-bad-version.json

@@ -0,0 +1,4 @@
+{
+	"kind": "tag",
+	"version": "v1"
+}

package/agent-template/.ai/blueprints/release/examples/invalid/plan-bad-branch.json

@@ -0,0 +1,7 @@
+{
+	"blueprint": "release@1.0.0",
+	"branch": "Michal/My Branch",
+	"files": ["modules/inventory/**"],
+	"gates": ["pnpm verify"],
+	"postMerge": []
+}

package/agent-template/.ai/blueprints/release/examples/valid/input.json

@@ -0,0 +1,5 @@
+{
+	"kind": "sandbox-eject",
+	"moduleId": "inventory.core",
+	"sessionId": "3f1c2d9e-0000-4000-8000-000000000000"
+}

package/agent-template/.ai/blueprints/release/examples/valid/plan.json

@@ -0,0 +1,20 @@
+{
+	"blueprint": "release@1.0.0",
+	"branch": "sandbox/inventory-3f1c2d9e",
+	"files": [
+		"modules/inventory/**",
+		"flowdular.json",
+		"platform/package.json",
+		"platform/src/generated/modules.server.ts",
+		"platform/src/generated/modules.client.ts",
+		"pnpm-lock.yaml"
+	],
+	"gates": [
+		"sandbox gates",
+		"pnpm --filter @flowdular/platform typecheck",
+		"pnpm verify"
+	],
+	"postMerge": [
+		"pnpm flowdular auth sync-scopes --module inventory.core --apply"
+	]
+}

package/agent-template/.ai/blueprints/release/gates.yaml

@@ -0,0 +1,20 @@
+schemaVersion: 1
+# What CI runs (.github/workflows/ci.yml) plus the sandbox eject gates.
+gates:
+  - id: sandbox-gates
+    command: eject stream runs spec-schema and module-schema once, then dependencies, typecheck, tests, format per draft module
+    required: true
+    appliesTo: sandbox-eject
+  - id: verify
+    command: pnpm verify
+    required: true
+  - id: build
+    command: pnpm build
+    required: true
+  - id: audit
+    command: pnpm audit --prod --audit-level high
+    required: true
+  - id: platform-typecheck
+    command: pnpm --filter @flowdular/platform typecheck
+    required: true
+    appliesTo: sandbox-eject

package/agent-template/.ai/blueprints/release/input.schema.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["kind"],
+	"properties": {
+		"kind": {
+			"type": "string",
+			"enum": ["sandbox-eject", "pull-request", "tag"]
+		},
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"sessionId": {
+			"type": "string",
+			"minLength": 8
+		},
+		"version": {
+			"type": "string",
+			"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+		}
+	}
+}

package/agent-template/.ai/blueprints/release/plan.schema.json

@@ -0,0 +1,46 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["blueprint", "branch", "files", "gates", "postMerge"],
+	"properties": {
+		"blueprint": {
+			"const": "release@1.0.0"
+		},
+		"branch": {
+			"type": "string",
+			"pattern": "^(sandbox|feat|fix|core|release)/[a-z0-9.-]+$"
+		},
+		"files": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"pnpm verify",
+					"pnpm build",
+					"pnpm audit --prod --audit-level high",
+					"sandbox gates",
+					"pnpm --filter @flowdular/platform typecheck"
+				]
+			},
+			"uniqueItems": true
+		},
+		"postMerge": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		}
+	}
+}

package/agent-template/.ai/blueprints/release/required-files.yaml

@@ -0,0 +1,19 @@
+schemaVersion: 1
+required: []
+inCommit:
+  sandbox-eject:
+    - modules/{module}/**
+    - flowdular.json (module enable)
+    - platform/package.json (module enable)
+    - platform/src/generated/modules.server.ts (module sync)
+    - platform/src/generated/modules.client.ts (module sync)
+    - pnpm-lock.yaml (pnpm install, when changed)
+  pull-request:
+    - the reviewed change plus the CLI outputs it required
+  tag:
+    - nothing; the tag points at main
+pullRequestBody:
+  - two sentences on what changed and why
+  - gate evidence: gate id, command, result
+  - post-merge step: pnpm flowdular auth sync-scopes --module <id> --apply against the deployment database
+  - no AI attribution footer, no em or en dashes

package/agent-template/.ai/blueprints/release/spec-requirements.yaml

@@ -0,0 +1,8 @@
+schemaVersion: 1
+status:
+  allowed:
+    - approved
+    - implemented
+checks:
+  - module.json version, spec specVersion and package.json version are equal
+  - status may move from approved to implemented once the module is enabled in the deployment

package/agent-template/.ai/blueprints/release/steps.yaml

@@ -0,0 +1,47 @@
+schemaVersion: 1
+steps:
+  - id: gates
+    role: module-executor
+    action: 'Sandbox: the six gates in the eject stream. Working tree: pnpm verify, pnpm build, pnpm audit --prod --audit-level high.'
+    inputs:
+      - 'working tree'
+    outputs:
+      - 'gate evidence'
+  - id: compose
+    role: module-executor
+    action: pnpm flowdular module enable <id> --apply for a new module (grants its scopes), pnpm flowdular module sync --apply otherwise; pnpm flowdular auth sync-scopes --module <id> --apply only to re-grant after a new permission.
+    inputs:
+      - 'modules/{module}/**'
+    outputs:
+      - 'flowdular.json'
+      - 'platform/package.json'
+      - 'platform/src/generated/*.ts'
+  - id: branch
+    role: module-executor
+    action: Branch sandbox/<module-dir>-<session-prefix> (or feat/, fix/, core/); commit only module files plus the CLI outputs; one logical change per commit.
+    inputs:
+      - 'diff'
+    outputs:
+      - 'branch'
+  - id: pull-request
+    role: module-executor
+    action: Short body, gate evidence, post-merge sync-scopes step, commands that produced generated files; no AI attribution.
+    inputs:
+      - 'branch'
+      - 'gate evidence'
+    outputs:
+      - 'pull request'
+  - id: review
+    role: reviewer
+    action: Reviewer checklist plus security-review when scopes or endpoints changed.
+    inputs:
+      - 'pull request'
+    outputs:
+      - 'review'
+  - id: post-merge
+    role: operator
+    action: Deploy; run pnpm flowdular auth sync-scopes --module <id> --apply with FD_AUTH_DATABASE pointing at the deployment; verify an owner sees the navigation entry. Tag v*.*.* to build the container.
+    inputs:
+      - 'merged main'
+    outputs:
+      - 'deployment'

package/agent-template/.ai/blueprints/security-review/README.md

@@ -0,0 +1,5 @@
+# security-review
+
+Read-only review of a module, package or pull request against `.ai/skills/auth-security-review/SKILL.md`. The reviewer writes no production code; findings go back to the author with a severity, a location, a concrete failure scenario, the rule violated and the fix. Gates are the read-only greps and the tests the skill lists.
+
+Run it for every change that adds or changes an endpoint, a scope, a token, a credential, or a CLI capability, and before a sandbox eject of a module that other tenants will use.

package/agent-template/.ai/blueprints/security-review/allowed-paths.yaml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+write: []
+deny:
+  - '**'
+notes:
+  - the review report is returned as text or a pull request review, not committed as a file

package/agent-template/.ai/blueprints/security-review/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "security-review",
+	"version": "1.0.0",
+	"risk": "read",
+	"agentRoles": ["reviewer"],
+	"executorProfiles": ["reviewer"],
+	"requiredReviewers": ["platform-owner"],
+	"requiresApprovedSpec": false
+}

package/agent-template/.ai/blueprints/security-review/examples/invalid/input-unknown-kind.json

@@ -0,0 +1,4 @@
+{
+	"kind": "deployment",
+	"target": "production"
+}

package/agent-template/.ai/blueprints/security-review/examples/invalid/plan-finding-without-scenario.json

@@ -0,0 +1,14 @@
+{
+	"blueprint": "security-review@1.0.0",
+	"checksRun": ["grep -rn \"new ServerRoute\" modules/inventory/src"],
+	"findings": [
+		{
+			"severity": "blocker",
+			"claim": "Looks unsafe.",
+			"location": "modules/inventory/src/api/endpoints.ts",
+			"rule": "AGENTS.md rule 5",
+			"fix": "Rewrite it."
+		}
+	],
+	"verdict": "changes-required"
+}

package/agent-template/.ai/blueprints/security-review/examples/valid/input.json

@@ -0,0 +1,4 @@
+{
+	"kind": "module",
+	"target": "inventory.core"
+}

package/agent-template/.ai/blueprints/security-review/examples/valid/plan.json

@@ -0,0 +1,19 @@
+{
+	"blueprint": "security-review@1.0.0",
+	"checksRun": [
+		"grep -rn \"new ServerRoute\" modules/inventory/src",
+		"grep -rn tenantId modules/inventory/src/api",
+		"pnpm --filter @flowdular/module-inventory test"
+	],
+	"findings": [
+		{
+			"severity": "blocker",
+			"claim": "Tenant id is read from the request body.",
+			"location": "modules/inventory/src/api/endpoints.ts:41",
+			"scenario": "A member of tenant A posts { tenantId: \"B\" } and creates a location in tenant B.",
+			"rule": "AGENTS.md rule 6",
+			"fix": "Use principalFromContext(octane)!.tenantId and remove the body field."
+		}
+	],
+	"verdict": "changes-required"
+}

package/agent-template/.ai/blueprints/security-review/gates.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 1
+# Read-only checks. Nothing executes this file.
+gates:
+  - id: raw-routes
+    command: grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth
+    expect: no output
+    required: true
+  - id: tenant-from-input
+    command: grep -rn tenantId modules/*/src/api | grep -v principalFromContext
+    expect: no output
+    required: true
+  - id: unbounded-body
+    command: grep -rn "request.json()" modules/*/src
+    expect: no output outside modules/auth and modules/users
+    required: true
+  - id: public-endpoints
+    command: 'grep -rn "kind: ''public''" modules/*/src'
+    expect: each hit has a written reason
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    required: true

package/agent-template/.ai/blueprints/security-review/input.schema.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["kind", "target"],
+	"properties": {
+		"kind": {
+			"type": "string",
+			"enum": ["module", "package", "pull-request"]
+		},
+		"target": {
+			"type": "string",
+			"minLength": 1
+		},
+		"diffRef": {
+			"type": "string",
+			"minLength": 1
+		}
+	}
+}

package/agent-template/.ai/blueprints/security-review/plan.schema.json

@@ -0,0 +1,65 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["blueprint", "checksRun", "findings", "verdict"],
+	"properties": {
+		"blueprint": {
+			"const": "security-review@1.0.0"
+		},
+		"checksRun": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		},
+		"findings": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": [
+					"severity",
+					"claim",
+					"location",
+					"scenario",
+					"rule",
+					"fix"
+				],
+				"properties": {
+					"severity": {
+						"type": "string",
+						"enum": ["blocker", "should-fix", "taste"]
+					},
+					"claim": {
+						"type": "string",
+						"minLength": 1
+					},
+					"location": {
+						"type": "string",
+						"minLength": 1
+					},
+					"scenario": {
+						"type": "string",
+						"minLength": 1
+					},
+					"rule": {
+						"type": "string",
+						"minLength": 1
+					},
+					"fix": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		},
+		"verdict": {
+			"type": "string",
+			"enum": ["approved", "changes-required"]
+		}
+	}
+}

package/agent-template/.ai/blueprints/security-review/required-files.yaml

@@ -0,0 +1,6 @@
+schemaVersion: 1
+required: []
+evidence:
+  - the exact grep commands run and their output
+  - the test commands run and their result
+  - one entry per finding with severity, claim, location, scenario, rule, fix

package/agent-template/.ai/blueprints/security-review/spec-requirements.yaml

@@ -0,0 +1,9 @@
+schemaVersion: 1
+# A review changes no spec. It checks that the spec and the code agree.
+status:
+  allowed:
+    - approved
+checks:
+  - permissions[].id equal the constants in src/acl/permissions.ts
+  - every endpoint permission appears in the spec
+  - a denial scenario and a tenant isolation scenario exist

package/agent-template/.ai/blueprints/security-review/steps.yaml

@@ -0,0 +1,38 @@
+schemaVersion: 1
+steps:
+  - id: surface
+    role: reviewer
+    action: List every route in src/api/endpoints.ts and check access, resolveIdentity, sessionMutationDenial order, readJsonObject bounds, tenant source, bound SQL, error envelope.
+    inputs:
+      - 'target'
+    outputs:
+      - 'endpoint table'
+  - id: scopes
+    role: reviewer
+    action: Compare spec permissions, src/acl/permissions.ts, endpoint access and client scope; check whether auth sync-scopes is part of the landing.
+    inputs:
+      - 'spec/module.yaml'
+      - 'src/acl/permissions.ts'
+    outputs:
+      - 'scope findings'
+  - id: greps
+    role: reviewer
+    action: Run the greps in .ai/skills/auth-security-review/SKILL.md section 5 and record the output.
+    inputs:
+      - 'target'
+    outputs:
+      - 'grep evidence'
+  - id: tests
+    role: reviewer
+    action: Confirm the 401, 403, cross-tenant, CSRF and validation tests exist and fail when their guard is removed.
+    inputs:
+      - 'tests/'
+    outputs:
+      - 'test evidence'
+  - id: report
+    role: reviewer
+    action: Findings by severity with a concrete failure scenario each; verdict approved or changes-required; no code changes.
+    inputs:
+      - 'evidence'
+    outputs:
+      - 'review report'

package/agent-template/.ai/examples/README.md

@@ -0,0 +1,8 @@
+# Examples
+
+Small, deliberately isolated files that show a shape. None of them is compiled or tested; `.ai/references/catalog` is the compiled reference for a module and `modules/auth/src/cli` for a CLI extension.
+
+- `client-contribution/`: `createClientContribution(context)` entry, contribution factory with `csrfToken` threading, an `ICON_PATHS` glyph, unique ids, a `WORKSPACE_SLOTS` widget.
+- `customer-cli-extension/`: `commands.json` catalog plus `defineCliExtension` implementation, metadata-identical.
+- `bad/`: three negative examples, each with a README naming the violated `AGENTS.md` rule and the repair blueprint: `missing-acl` (raw route without access), `tenant-from-body` (tenant id from input, no session denial), `client-imports-server` (browser code importing the database repository).
+- `module-create/task-packet.json`: the task packet shape validated by `validateTaskPacket` in `packages/harness/src/task-packet.ts`. No runtime consumes packets today; the sandbox works from briefs and role turns.

package/agent-template/.ai/examples/bad/client-imports-server/README.md

@@ -0,0 +1,20 @@
+# Bad example: client file importing a server module
+
+`api.ts` sits under `src/client` and imports `../services/database-repository.ts`, which pulls in `@flowdular/sdk/database` and its `node:fs`, `node:path` and `node:async_hooks` imports. The Vite client build fails on the Node built-ins, and even where it compiled the browser would hold a database handle and a `tenantId` parameter chosen by the caller, bypassing every endpoint check.
+
+Violated rules: `AGENTS.md` 5 and 6 (data reaches the client only through an endpoint that resolves identity and takes the tenant from the principal) and the layering in `.ai/skills/core-extend/SKILL.md` (client code imports `@flowdular/sdk/client`, `@flowdular/sdk/ui`, `octane`, `segment-state`, and the module's own `src/client` and `src/domain` types; never `src/services` or `src/server`).
+
+Repair with the `bug-fix` blueprint: replace the import with a `fetch` in `src/client/api.ts` as in `.ai/references/catalog/src/client/api.ts`:
+
+```ts
+export async function loadCustomers(): Promise<readonly Customer[]> {
+	const response = await fetch('/api/customers', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return (await payload<{ readonly customers: readonly Customer[] }>(response))
+		.customers;
+}
+```
+
+The server endpoint supplies the tenant from the principal; the client never names one.

package/agent-template/.ai/examples/bad/client-imports-server/api.ts

@@ -0,0 +1,12 @@
+/* WRONG: browser code importing the server repository. */
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { DatabaseCustomerRepository } from '../services/database-repository.ts';
+import type { Customer } from '../domain/types.ts';
+
+declare const database: DatabaseHandle;
+
+const repository = new DatabaseCustomerRepository(database);
+
+export function loadCustomers(tenantId: string): Promise<readonly Customer[]> {
+	return repository.list(tenantId);
+}

package/agent-template/.ai/examples/bad/missing-acl/README.md

@@ -0,0 +1,23 @@
+# Bad example: endpoint without access control
+
+`endpoints.ts` mounts `/api/customers` with `new ServerRoute` from `@octanejs/app-core`. Nothing resolves an identity, nothing checks a permission, and `listAll()` has no tenant. Anyone who can reach the server reads every tenant's customers.
+
+Violated rules: `AGENTS.md` 5 (every endpoint is `defineEndpoint` with `access: { kind: 'permission' }` and `resolveIdentity: endpointIdentityFromContext`) and 6 (tenant id from the principal). The security skill's first grep (`grep -rn "new ServerRoute" modules/*/src | grep -v modules/auth`) finds it.
+
+Repair with the `bug-fix` blueprint (or `edit-module`, change class `endpoint`):
+
+```ts
+const list = defineEndpoint({
+	id: 'customers.records.list',
+	path: '/api/customers',
+	methods: ['GET'],
+	access: { kind: 'permission', permission: CUSTOMER_PERMISSIONS.read },
+	resolveIdentity: endpointIdentityFromContext,
+	handler: ({ octane }) =>
+		jsonResponse({
+			customers: runtime.service().list(principalFromContext(octane)!.tenantId),
+		}),
+});
+```
+
+Reference: `.ai/references/catalog/src/api/endpoints.ts`.

package/agent-template/.ai/examples/bad/missing-acl/endpoints.ts

@@ -0,0 +1,12 @@
+/* WRONG: a raw ServerRoute with no permission and no identity resolver. */
+import { ServerRoute } from '@octanejs/app-core';
+import type { CustomerRuntime } from '../server/runtime.ts';
+
+export function createCustomerRoutes(runtime: CustomerRuntime) {
+	const list = new ServerRoute({
+		path: '/api/customers',
+		methods: ['GET'],
+		handler: () => Response.json({ customers: runtime.service().listAll() }),
+	});
+	return [list] as const;
+}

package/agent-template/.ai/examples/bad/tenant-from-body/README.md

@@ -0,0 +1,19 @@
+# Bad example: tenant id from the request body
+
+`endpoints.ts` has a permission and an identity resolver, and still lets a member of tenant A create a customer in tenant B by posting `{ "tenantId": "B", "name": "..." }`. The permission check passes because the principal holds `customers.records.manage` in its own tenant; the body decides where the row lands. The mutation also skips `sessionMutationDenial`, so a cross-site form post with a valid cookie would be accepted.
+
+Violated rules: `AGENTS.md` 6 (tenant id only from `principalFromContext(octane)!.tenantId`) and 7 (`sessionMutationDenial(octane, auth)` first on every mutation). The security skill's grep `grep -rn tenantId modules/*/src/api | grep -v principalFromContext` finds it.
+
+Repair with the `bug-fix` blueprint: remove the body field, take `auth: AuthRuntime` in `createCustomerRoutes`, and write
+
+```ts
+handler: async ({ octane }) => {
+	const denial = sessionMutationDenial(octane, auth);
+	if (denial) return denial;
+	const value = await readJsonObject(octane.request);
+	const tenantId = principalFromContext(octane)!.tenantId;
+	...
+}
+```
+
+Add the test from `.ai/skills/test-hardening/SKILL.md`: a principal of tenant A posting `tenantId: 'B'` still creates in A (the field is ignored or rejected with 400).

package/agent-template/.ai/examples/bad/tenant-from-body/endpoints.ts

@@ -0,0 +1,33 @@
+/* WRONG: the tenant id is read from the request body. */
+import {
+	defineEndpoint,
+	jsonResponse,
+	readJsonObject,
+	requiredString,
+} from '@flowdular/sdk/server';
+import { endpointIdentityFromContext } from '@flowdular/sdk/modules/auth/server';
+import { CUSTOMER_PERMISSIONS } from '../acl/permissions.ts';
+import type { CustomerRuntime } from '../server/runtime.ts';
+
+export function createCustomerRoutes(runtime: CustomerRuntime) {
+	const create = defineEndpoint({
+		id: 'customers.records.create',
+		path: '/api/customers',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: CUSTOMER_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const value = await readJsonObject(octane.request);
+			const tenantId = requiredString(value, 'tenantId');
+			return jsonResponse(
+				{
+					customer: runtime
+						.service()
+						.create(tenantId, { name: requiredString(value, 'name') }),
+				},
+				201,
+			);
+		},
+	});
+	return [create.serverRoute] as const;
+}