spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/templates/agent/skills/spine-new-function/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spine-new-function
+description: "Decide when a custom Netlify function is allowed (admin-data can't cover the case) and write it correctly."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You decide whether a piece of server logic may become a custom function, and
+write it when it may. **Default answer: no** — runtime record CRUD belongs to
+`/api/admin-data`, full stop.
+
+## When a custom function IS allowed
+
+A `custom/functions/` (or app `functions/`) handler is legitimate only when
+`/api/admin-data` cannot express the work:
+
+- **Non-record operations** — compute, aggregation, export, file transform.
+- **External orchestration** — call an integration, fan out to several
+  services, run a multi-step protocol in one request.
+- **Inbound webhooks** — verify a signature and normalize a payload before
+  handing it to a pipeline (see `spine-add-integration`).
+- **Scheduled/system work** — timer-driven batch jobs that need server
+  context.
+- **Auth-adjacent flows** — invite acceptance, api-key exchange, registration
+  handshakes (see `.framework/src/instructions/api-keys.md` and
+  `integrations.md`).
+
+It is **never** allowed for: listing/creating/updating/deleting `items`,
+`threads`, `messages`, `links`, `attachments`, `watchers`, or other runtime
+records — those calls bypass permission checks, type resolution, audit, and
+triggers inside admin-data. See
+`.framework/src/instructions/reference/api/admin-data.md`.
+
+## Writing the function
+
+1. Read `.framework/src/instructions/reference/api/admin-data.md` and
+   `.framework/src/instructions/reference/functions/index.md` for the
+   endpoint inventory your function may use.
+2. Place it in `custom/functions/` (project-scoped) or the app's
+   `functions/` dir; assemble picks it up at build time.
+3. Inside the function, import shared helpers via `./_shared/*` (the
+   assembled flat layout) — never via relative paths into `.framework/`.
+4. Authenticate with the platform auth helpers (principal resolution,
+   role checks). Use `adminDb` only when bypassing RLS is truly intended.
+5. Keep secrets in env — `VITE_*` vars are public; service keys are not.
+6. Register a `custom_*` scheduled/function section in `netlify.toml` if it
+   needs a schedule — those sections are app-owned and survive upgrade.
+
+## Verify
+
+- `npm run typecheck:functions` — functions are typechecked against the
+  assembled layout.
+- Exercise it once via the assembled function endpoint, not by shortcutting
+  through app code.
+
+## Rules
+
+- If a proposed function reads/writes runtime records, redirect the design to
+  `/api/admin-data` and say why.
+- One function per edge case — no catch-all "custom-api.ts" grab bags.

package/.framework/templates/agent/skills/spine-new-type/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spine-new-type
+description: "Create a new Spine type — pick kind/slug, author design_schema, seed the types row, and verify generic rendering."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You create a new Spine type: a `public.types` row whose `design_schema`
+governs how runtime records validate, render, and authorize.
+
+## When to invoke
+
+- A new domain entity is needed (work item, ticket, course, ...).
+- An existing type needs its schema extended (use `spine-schema` for the JSON).
+
+## Steps
+
+1. **Read the contract.** `.framework/src/instructions/types.md` describes the
+   fields (`slug`, `kind`, `ownership`, `is_active`, `icon`, `color`,
+   `design_schema`, `validation_schema`) and their downstream effects. The full
+   field reference is `.framework/src/instructions/reference/design-schema.md`;
+   `.framework/src/instructions/concepts/runtime-records.md` covers how types
+   stamp records.
+
+2. **Pick `kind` and `slug`.**
+   - `kind` = the runtime table the records live in: `item` (default for
+     domain records), `thread`, `message`, `link`, `attachment`, `watcher`,
+     `person`, `account`.
+   - `slug` is unique **globally per kind** — type seeds use
+     `conflict: "kind,slug"` with `inject_app_id: false`. Check existing slugs
+     before choosing; duplicates break `resolveTypeId` lookups.
+
+3. **Author `design_schema`.** Minimum required shape:
+   - `scope`: `account` (default) or `platform`.
+   - `fields`: every field gets `data_type`, `label`, `required`.
+   - `views`: `default_list` (table fields + `default_sort`) and
+     `default_detail` (sections → fields) — required for generic apps.
+   - `record_permissions`: base grant per role; at least `system-admin`.
+   - `functionality`: `null` until automation bindings are confirmed.
+   See the `spine-schema` skill for the full checklist and valid values.
+
+4. **Validate the JSON:** `npx spine-framework validate-schema <file>`.
+
+5. **Deliver the row.** Types ship as app seed data (`seed/types.json`,
+   `conflict: "kind,slug"`, `inject_app_id: false`) or are created through the
+   admin UI / `admin-data`. Never write migration `INSERT`s that bypass the
+   seed/type-creation path unless the task is explicitly a migration.
+
+6. **Verify rendering.** Records store `system: true` fields at
+   `record.<field>` and the rest at `record.data.<field>` — check the generic
+   list/detail views render from `views` and the permission grants behave.
+
+## Rules
+
+- `validation_schema` is generated — never author it by hand.
+- Changing `data_type` on a field with existing records does not migrate data.
+- `system: true` fields restrict `write` to `system-admin` when the
+  record-level grant would otherwise allow it.
+- Verification: `validate-schema` clean + a created record reads back with
+  the expected `data` shape.

package/.framework/templates/agent/skills/spine-schema/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: spine-schema
+description: "Author and validate a Spine type's design_schema — fields, views, record_permissions — before saving it to public.types."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You author and validate `design_schema` JSON for Spine types. The schema drives
+permissions, validation, and generic UI rendering — mistakes surface as empty
+or unwriteable records.
+
+## When to invoke
+
+- A new type needs a `design_schema`.
+- An existing type or runtime record is not behaving as expected.
+- A schema needs validation before it is saved to `public.types`.
+
+## Inputs to gather
+
+- `kind` — the runtime table the type governs (`item`, `thread`, `message`,
+  `link`, `attachment`, `watcher`, `person`, `account`).
+- `slug` — unique per `kind`; duplicates break `resolveTypeId`/`.single()`.
+- `scope` — `account` (default) or `platform`.
+- Whether the app is generic (`apps.renderer = "generic"`) or custom —
+  generic apps require complete `views`.
+
+## Authoring procedure
+
+1. Read `.framework/src/instructions/types.md` for the entity contract,
+   `.framework/src/instructions/concepts/design-schema.md` for the model, and
+   `.framework/src/instructions/reference/design-schema.md` for the field
+   reference.
+2. Draft `design_schema` with the minimum shape:
+   - `fields` — each field needs `data_type`, `label`, `required`.
+   - `views.default_list` — `type: "list"`, `fields`, `default_sort`.
+   - `views.default_detail` — `type: "detail"`, `sections[].fields`.
+   - `record_permissions` — base grant per role; at least `system-admin`.
+   - `functionality` — `null` until automation bindings are confirmed.
+3. Apply the permission rule: `record_permissions` is the most restrictive
+   grant. Use `fields.<name>.permissions` **only** to loosen a field beyond the
+   base grant or to restrict a `system: true` field's `write`.
+4. Mark `system: true` only for fields stored as top-level record columns;
+   everything else lives in `record.data.<field>`.
+
+## Valid values
+
+- `data_type`: `text`, `textarea`, `rich_text`, `email`, `phone`, `url`,
+  `number`, `currency`, `range`, `date`, `datetime`, `boolean`, `checkbox`,
+  `select`, `multiselect`, `radio`, `color`, `file`, `image`, `json`,
+  `reference`, `address`.
+- `display_type`: `text`, `input`, `textarea`, `rich_text`, `select`,
+  `multiselect`, `radio`, `checkbox`, `switch`, `date_picker`,
+  `datetime_picker`, `color_picker`, `file_upload`, `image_upload`,
+  `range_slider`, `badge`, `timestamp`, `currency`, `number`.
+- `select`/`multiselect`/`radio` fields require non-empty `options`.
+
+## Validate
+
+```bash
+npx spine-framework validate-schema path/to/design_schema.json
+```
+
+Exit code 0 = ok; errors are printed with their `fields.*`/`views.*` path.
+Run `npx spine-framework validate-app <dir>` instead when checking a whole app
+package (manifest, seeds, structure).
+
+## Rules
+
+- Never guess `data_type`/`display_type` values — use only the lists above.
+- Never widen `record_permissions` to fix a field-level problem; add a field
+  override instead.
+- Report the schema diff and any records that need restamping before saving.

package/.framework/templates/agent/skills/spine-test/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: spine-test
+description: "Run and write tests in a Spine project — vitest suites, typecheck, integrity verify, and where test files belong."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You run the project's verification suite and add tests in the right places.
+
+## When to invoke
+
+- Before finishing any code change (the verify gate).
+- When a change needs a new test.
+- When a test fails and the suite layout is unfamiliar.
+
+## Commands
+
+```bash
+npm run typecheck            # tsc over assembled + framework + custom sources
+npm run test                 # vitest run — unit + api suites
+npm run verify               # .spine-manifest.json integrity (fail-closed)
+npx vitest run <file>        # one test file during development
+npm run test:unit            # unit suite only, if present in scripts
+```
+
+The test/CI reference pages live at
+`.framework/src/instructions/reference/functions/tests.md` and
+`.framework/src/instructions/reference/cli.md`.
+
+## Where tests live
+
+- `.framework/tests/` — framework-owned suites. Do not add project tests
+  here; the tree is sealed and upgrade-overwritten.
+- `custom/tests/` — project-level tests; matched by `vitest.config.ts`.
+- `custom/apps/<slug>/tests/` or colocated `*.test.ts` — app-owned tests.
+
+## Writing a test
+
+1. Follow the existing unit-test style: `vitest` imports, `mkdtempSync` under
+   `os.tmpdir()` for filesystem fixtures, `vi.mock`/`vi.hoisted` for module
+   fakes, `vi.spyOn(console, 'log')` to silence CLI output.
+2. `.framework/tests/setup.ts` stubs `SUPABASE_URL`/`SUPABASE_ANON_KEY`/
+   `SUPABASE_SERVICE_ROLE_KEY` — unit tests must not need real credentials.
+3. Integration tests hitting a live database are excluded from the shipped
+   suite — keep new tests unit-level unless told otherwise.
+
+## Failure triage
+
+- **typecheck** — fix compile errors first; runtime failures under them are
+  noise.
+- **verify** — a `.framework/` file changed; find the local edit and revert
+  (or `upgrade --force`).
+- **test** — read the assertion, then the fixture; check mocks before
+  suspecting logic.
+- **doctor** — `npx spine-framework doctor --fix` surfaces env/db/wiring
+  problems that masquerade as test failures.
+
+## Rules
+
+- Never weaken or skip a failing test to go green — fix the cause.
+- New behavior gets a test in the same PR unless the task says otherwise.
+- Keep fixtures hermetic: temp dirs, no network, no real credentials.

package/.framework/templates/agent/skills/spine-troubleshoot/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: spine-troubleshoot
+description: "Debug a Spine issue — use deliveries, executions, logs, doctor, and the integrity manifest to isolate framework vs app faults."
+allowed-tools:
+  - read
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You debug Spine projects: form a hypothesis, check the observability surfaces,
+and isolate whether the fault is in framework, app, config, or data.
+
+## When to invoke
+
+- A pipeline, trigger, timer, delivery, or agent is not behaving.
+- Records render empty/unwriteable or permissions deny expected access.
+- `npm run verify`, `npm run typecheck`, `npm run test`, or doctor report problems.
+
+## First move — doctor
+
+```bash
+npx spine-framework doctor --fix
+```
+
+Doctor checks environment, database, migrations, test runs, `runtime_wiring`
+(dangling trigger/pipeline/action references), manifest integrity, and agent
+assets. Warnings name the broken reference — start there.
+
+## Observability surfaces
+
+- `.framework/src/instructions/deliveries.md` — outbound delivery attempts:
+  status, retries, response bodies. First stop for webhook/integration issues.
+- `.framework/src/instructions/concepts/observability.md` — the logging and
+  execution model; `.framework/src/instructions/operations/` — admin-UI
+  runbooks for logs and executions.
+- `.framework/src/instructions/reference/functions/logs.md`,
+  `.framework/src/instructions/reference/functions/pipeline-executions.md`,
+  `.framework/src/instructions/reference/cli.md` — endpoint/CLI spelling.
+- `.framework/src/instructions/triggers.md` / `timers.md` / `pipelines.md` —
+  field-level config reference when a record's wiring looks wrong.
+
+## Common failure patterns
+
+- **Active pipeline does nothing** — `stages` array empty or every
+  `stage_type` points at an inactive/missing action (doctor `runtime_wiring`
+  flags this).
+- **Record renders empty** — `design_schema.views` missing `default_list`/
+  `default_detail`, unknown `display_type`, or fields stored under
+  `record.data` but read as top-level (`system: true` mismatch).
+- **Permission denied unexpectedly** — `record_permissions` is the base
+  grant; check the role's record-level grant before field overrides. See
+  `.framework/src/instructions/concepts/permissions.md` and
+  `.framework/src/instructions/roles.md`.
+- **Trigger never fires** — `is_active` false, `event_type` mismatch, or
+  `type_slug`/`pipeline_slug` not resolving (doctor flags all of these).
+- **Upgrade verify fails** — `.framework/` was edited locally; the tree is
+  sealed. Revert or `npx spine-framework upgrade --force` to resync.
+- **Env issues** — missing `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY`; copy
+  `.env.example` → `.env` and fill in credentials.
+
+## Isolation procedure
+
+1. Reproduce with the smallest path (one record, one event, one call).
+2. Check deliveries/executions for the failing run's error text.
+3. Compare config against the entity doc's field reference.
+4. If the fault is inside `.framework/`, report it — do not patch core.
+5. Verify the fix: rerun the failing path + `npm run test` / doctor.
+
+## Rules
+
+- Trust code over docs when they conflict; note the inconsistency.
+- Never "fix" a symptom by widening permissions or disabling RLS — find the
+  wiring bug instead.

package/.framework/templates/agent/skills/spine-upgrade/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: spine-upgrade
+description: "Explain and run spine-framework upgrade — what it rewrites, what it preserves, and the dry-run/force flags."
+allowed-tools:
+  - read
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You run and explain `spine-framework upgrade` — the command that syncs a
+project's framework-owned files to the spine-framework version installed in
+`node_modules`.
+
+## When to invoke
+
+- `package.json` `spine-framework` pin was bumped and the project must resync.
+- The user asks what upgrade will change before running it.
+
+CLI spelling and flags live in `.framework/src/instructions/reference/cli.md`.
+
+## What it does
+
+1. Verifies `.spine-manifest.json` exists and no framework file was modified
+   locally (abort with the list; `--force` overrides).
+2. Copies the new package's framework files over `.framework/`, `config/`,
+   `scripts/`, `bin/` — added/changed/removed report.
+3. Merges `package.json`: framework deps and scripts; exact `spine-framework`
+   pin; customer-added deps and scripts preserved.
+4. Re-renders `netlify.toml`: framework blocks replaced, app-owned
+   `[functions."custom_*"]` sections preserved verbatim (backup at
+   `netlify.toml.bak` when it changes).
+5. Refreshes agent assets: replaces the `<!-- spine-framework:begin/end -->`
+   block inside `AGENTS.md` (everything outside the markers — including the
+   user section — is preserved) and replaces `.devin/skills/spine-*/`
+   wholesale (non-`spine-*` skill dirs are customer-owned and untouched).
+6. Regenerates `.spine-manifest.json` at the new version.
+
+## Never overwritten
+
+- `AGENTS.md` content outside the framework markers.
+- `.devin/skills/` directories not named `spine-*`.
+- `custom/`, `spine.config.json`, `.env`, netlify.toml `custom_*` sections,
+  customer `package.json` deps/scripts.
+
+## Procedure
+
+```bash
+npx spine-framework upgrade --dry-run   # change report, writes nothing
+npx spine-framework upgrade             # apply
+npx spine-framework upgrade --force     # allow overwriting modified files
+```
+
+After a real upgrade:
+
+```bash
+npm install                          # resolve the new dep set
+npm run verify                       # confirm frozen integrity
+npx spine-framework migrate          # apply new migrations (if reported)
+npm run typecheck && npm run test    # confirm the tree still builds/tests
+```
+
+## Rules
+
+- Always `--dry-run` first when the project may have local `.framework/` edits.
+- New migrations are *reported*, never run — `migrate` applies them.
+- Upgrade is file-sync, not git-aware; rollback means `git`.
+- A modified `.framework/` file must be resolved (revert or `--force`) —
+  never silently accept a mixed-version core.

package/.framework/templates/project.json

@@ -10,7 +10,6 @@
     ".framework/src",
     ".framework/tests",
     ".framework/docs",
-    ".framework/mcp",
     ".framework/templates"
   ],
   "framework_files": [
@@ -50,6 +49,10 @@
     "bin/ws-shim.mts",
     "bin/ws-shim.ts"
   ],
+  "agent_files": [
+    { "source": ".framework/templates/agent/AGENTS.md", "dest": "AGENTS.md", "merge": "framework-block" },
+    { "source": ".framework/templates/agent/skills", "dest": ".devin/skills", "merge": "dir-replace" }
+  ],
   "exclude_globs": [
     "**/.env",
     "**/.env.local",