@gregiteen/ssss-cli 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to the SSSS (Structured Semantic Syntax System) spec will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.0] - 2026-07-02
+### Changed
+- **BREAKING: universal frontmatter enforcement** — every SSSS document primitive
+  now requires `type`, `title`, `description`, and `timestamp`. Primitive-specific
+  required fields still apply after these universal fields.
+- Registry `spec_version` -> `0.6`; spec header -> v0.6 draft. Reference bundle
+  metadata now targets SSSS core `0.6`.
+- The reference engine, bundle validator, skill validator, runtime helpers,
+  scaffold output, conformance fixtures, shipped skills, and reference bundle now
+  share the universal metadata requirement.
+
+### Added
+- OKF compatibility guidance documenting `resource`, `tags`, and `aliases` as
+  recommended discovery enrichment fields while keeping the mandatory universal
+  metadata minimal and deterministic.
+- Security hardening for the reference engine and CLI:
+  - VFS paths now reject absolute, root, dot-segment, empty-segment, backslash,
+    and directory targets.
+  - `workspace_id`, `idempotency_key`, and role names are constrained to safe
+    filesystem identifiers.
+  - Idempotency replay is bound to a request hash; same-key/different-payload
+    requests now fail as conflicts.
+  - Leases fail closed when unreadable and no longer derive filenames directly
+    from raw VFS paths.
+  - Bundle validation rejects unsafe and duplicate file paths, and export refuses
+    symlinked vault entries.
+  - Autolink skips symlinked Markdown targets before `--write`.
+  - Repo-local skill utility scripts avoid shell-string execution and validate
+    write-target names.
+
+## [0.6.0] - 2026-07-02
+### Added
+- **Workflow Runtime & Daemon Contract (spec §11.8)** — standardizes workflow
+  trigger evaluation across daemon, cron, webhook, file-change, event, condition,
+  and manual runtimes. Workflows own `triggers[]`; external schedulers are only
+  wake-up mechanisms.
+- **`@ssss/cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
+  `createRunEnvelope()` helpers derive `workflow_triggered` events, task
+  documents, and run documents through the Operation Contract.
+- **Runtime conformance metadata/checks** — `conformance/fixtures.json` v1.3.0
+  declares trigger/misfire/concurrency vocabularies and proves duplicate daemon
+  ticks replay idempotently.
+
+### Changed
+- Registry `spec_version` -> `0.5`; spec header -> v0.5 draft. Reference bundle
+  metadata now targets SSSS core `0.5`.
+
+## [0.5.0] - 2026-06-25
+### Added
+- **`ssss new <dir>` scaffolder** — bootstrap a fresh SSSS-native repo in one command:
+  a starter `vault/` of core primitives (incl. a `tenant_private` task to demonstrate
+  the sale-drop), a dependency-free conformance test (`node --test`) that replays the
+  canonical fixtures through the engine and round-trips the vault as a `sale` bundle,
+  plus `package.json` (pinned to the matching `@ssss/cli` tag), `CLAUDE.md`, `README`,
+  and `.gitignore`. Flags: `--with-total-recall` (wire the Total Recall memory OS),
+  `--install` (npm install + Total Recall init + verify), `--ref`, `--name`, `--force`,
+  `--no-git`. All shelling-out uses `execFileSync` with fixed argv (no shell). Docs:
+  `ssss help scaffold`.
+
+## [0.4.0] - 2026-06-24
+### Added
+- **The `.ucw` bundle format (spec §16, registry `bundle`)** — the canonical transportable
+  package of a vault: a manifest plus path-sorted files, content-hashed for integrity. The
+  manifest declares `ssss_core_version`, `required_extensions`, `export_profile`,
+  `primitive_inventory` (registry-driven, replacing ultrachat's closed `categories` enum),
+  `provisioning[]`, `parameters[]`, and `provenance{content_hash, exporter, signature?}`.
+  Harvested from ultrachat's `WorkspaceVfsPackageService` and generalized to be portability-
+  and registry-driven.
+- **The provisioning contract (spec §17, registry `provisioning`)** — three deterministic,
+  idempotent verbs: `export` (pure, profile-filtered), `provision` (params + link-integrity
+  + id-remap → replayable envelope plan), `import` (engine replay, idempotent via
+  idempotency_key). Adopts ultrachat's `WorkspaceProvisioningStep.mode`/`system` and
+  `WorkspaceGraphEdge.relation` as the canonical binding/dependency vocabularies, plus
+  `installMode` composition and structural-only `migration`+`patch` upgrades.
+- **Reference engine for bundles (`src/bundle.mjs`)** — dependency-free `exportBundle`,
+  `validateBundle`, `provisionBundle`, `importBundle` over the registry bundle schema.
+- **Reference bundle (`conformance/reference-bundle.ucw.json`, "Festival in a Box")** — a
+  real `sale`-profile bundle, built deterministically by `scripts/build-reference-bundle.mjs`.
+  Proves the §5.5 keystone: structural + resource_bound files ship, the `tenant_private`
+  ticket record is dropped. Round-tripped (validate → provision → import → re-import) by
+  `ssss conformance --engine`; 6/6 bundle/provisioning checks pass alongside the 9 fixtures.
+- **`language_convention` documented (spec §11.7)** — the festech-shipped, `structural`
+  presentation-overlay primitive, formally placed in the semantic layer.
+- **CLI command surface for the full lifecycle** — `ssss export`, `validate`, `inspect`,
+  `provision`, and `import` wire the bundle/provisioning verbs to the command line, plus
+  `ssss help [topic]` serving offline docs from `docs/help/` and `ssss version`. Each
+  command has its own `--help`. Shared parsing/formatting in `scripts/lib/cli.mjs`.
+- **Open-source packaging** — `README.md`, `LICENSE` (ISC), `.gitignore`, and
+  `package.json` metadata (`engines`, `repository`, `files`) so `@ssss/cli` is
+  publishable and the runtime-read paths (`VERSION`, `docs/help`) ship in the tarball.
+
+### Changed
+- Registry `spec_version` → `0.4`; spec header + §14 → v0.4. Engine exports add `./bundle`.
+
+## [0.3.0] - 2026-06-24
+### Added
+- **Portability classification (spec §5.5, registry `portability`)** — every document
+  primitive now declares a portability class: `structural` (the sellable business model),
+  `tenant_private` (the operator's private data, never sold), or `resource_bound` (needs a
+  real resource bound at provision). Export profiles `backup | template | sale` are filters
+  over these classes; `template`/`sale` exports MUST drop all `tenant_private` primitives.
+  Files MAY override their type default with `x_portability`. Lifted and generalized from
+  ultrachat's ad-hoc export filter in `WorkspaceVfsPackageService`.
+- **`delete` envelope (spec §6.2)** — promoted from festech's `SsssOperationService` into
+  the canonical Operation Contract as the fourth envelope type. Removes a replace-type file,
+  rejects append-type targets, and emits a deletion event for audit. Idempotent.
+- **Reference engine (`src/engine.mjs`, `src/registry.mjs`, `src/frontmatter.mjs`)** — the
+  canonical, dependency-free `@ssss/cli` Operation Contract engine. Harvested from total-recall
+  (§6.3 pipeline, idempotency replay from the audit log, `buildRepair`/§9 repair blocks) and
+  festech (`delete` envelope, `resolveContainedPath` path-traversal guard, registry-driven
+  content validation). Validates content against `registry/core.json` + `registry/extensions/*`
+  with no per-type code and no Zod/YAML dependency. Runs all 9 conformance fixtures in-process
+  via `ssss conformance --engine` (now wired into `npm test`).
+
+### Changed
+- Registry now defines **5 contract primitives** (added `delete`); `spec_version` → `0.3`.
+- §5.1 Document Primitives table gains a **Portability** column.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Greg Iteen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# SSSS — Structured Semantic Syntax System
+
+> A database-free, Markdown-first schema and mutation contract for AI-agent state.
+> Turn a running business into a single tradeable file — *a festival in a box.*
+
+[![conformance](https://img.shields.io/badge/conformance-fixtures%20%2B%20runtime%20%2B%20bundle-brightgreen)](conformance/)
+[![spec](https://img.shields.io/badge/spec-v0.6%20draft-blue)](docs/ssss-spec.md)
+[![OKF](https://img.shields.io/badge/OKF-v0.1%20compatible-blue)](docs/ssss-spec.md)
+
+SSSS is the vendor-neutral standard and reference implementation shared by
+[festech.live](https://festech.live), **ultrachat**, and **total-recall**. It defines:
+
+- **Document primitives** — typed Markdown files with YAML frontmatter (`workflow`,
+  `rule`, `page`, `assistant`, …), validated against a registry, not hand-written code.
+- **The Operation Contract** (§6) — four envelope types (`operation` / `patch` /
+  `event` / `delete`) for mutating a vault, with idempotency replay and audit.
+- **The Workflow Runtime Contract** (§11.8) — workflows own triggers; daemons,
+  crons, and webhooks derive idempotent event/task/run envelopes from the vault.
+- **Portability classification** (§5.5) — the keystone: every primitive is
+  `structural`, `tenant_private`, or `resource_bound`, so a vault can be *sold*
+  without leaking the operator's private data.
+- **The `.ucw` bundle format** (§16) and **provisioning contract** (§17) — package a
+  vault, then `export → provision → import` it into a fresh tenant, deterministically.
+
+This package, `@ssss/cli`, is **dependency-free**: a host needs neither Zod nor a YAML
+library to be conformant. The reference engine *is* the validator.
+
+## Install
+
+```bash
+npm install -g @ssss/cli      # the `ssss` command
+# or use it as a library:
+npm install @ssss/cli
+```
+
+Requires Node 18+. No runtime dependencies.
+
+## Start a new project
+
+```bash
+ssss new my-app --install                # scaffold + install + run the conformance test
+ssss new my-app --with-total-recall      # also wire the Total Recall memory OS
+```
+
+Scaffolds a starter `vault/`, a dependency-free conformance test, and a `CLAUDE.md`.
+See `ssss help scaffold`.
+
+## Quick start — the lifecycle
+
+```
+vault ──export──▶ .ucw bundle ──provision──▶ envelope plan ──import──▶ new vault
+        (§16, pure)            (§17, params + links)        (§6, idempotent)
+```
+
+```bash
+# 1. Package a vault as a sellable bundle (drops tenant-private data)
+ssss export ./my-vault --profile sale --out festival.ucw.json
+
+# 2. Inspect / verify it
+ssss inspect  festival.ucw.json --files
+ssss validate festival.ucw.json
+
+# 3. Stand up a fresh tenant from it
+ssss import festival.ucw.json --vault ./new-tenant \
+  --param business_name="Acme Fest" --param domain=acme.live
+
+# Re-running import commits nothing — it is idempotent.
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `ssss new <dir>` | Scaffold a new SSSS project (`--with-total-recall`, `--install`). |
+| `ssss export <vault>` | Package a vault into a `.ucw` bundle (§16). Pure & deterministic. |
+| `ssss validate <bundle>` | Check a bundle against the schema + portability rules. |
+| `ssss inspect <bundle>` | Human-readable summary (manifest, inventory, params, steps). |
+| `ssss provision <bundle>` | Plan an install: params + link integrity → envelopes (§17). |
+| `ssss import <bundle>` | Replay a bundle/plan into a vault via the engine (idempotent). |
+| `ssss autolink [dir]` | Generate OKF wiki-links across a vault. |
+| `ssss conformance` | Run the canonical conformance suite (§12). |
+| `ssss help [topic]` | Local docs: `runtime`, `portability`, `bundle`, `provisioning`, … |
+
+Run `ssss <command> --help` for flags, or `ssss help <topic>` for concepts.
+
+## Use as a library
+
+```js
+import { createEngine } from '@ssss/cli/engine';
+import { exportBundle, validateBundle, provisionBundle, importBundle } from '@ssss/cli/bundle';
+import { planWorkflowTrigger } from '@ssss/cli/runtime';
+
+const bundle = exportBundle('./my-vault', { profile: 'sale', name: 'Festival in a Box' });
+const { valid, errors } = validateBundle(bundle);
+
+const engine = createEngine();
+const plan = provisionBundle(bundle, { parameters: { domain: 'acme.live' }, workspaceId: 'ws-1' });
+importBundle(plan.plan, './new-tenant', engine);
+
+const workflowContent = `---
+type: workflow
+name: "Daily Digest"
+---
+
+1. Gather messages.
+2. Summarize.
+3. Send digest.
+`;
+const runtimePlan = planWorkflowTrigger({
+  workflowPath: 'workflows/daily-digest/WORKFLOW.md',
+  workflowContent,
+  workspaceId: 'ws-1',
+  trigger: { type: 'cron', id: 'daily-0800', cron: '0 8 * * *' },
+  scheduledFor: '2026-07-02T14:00:00.000Z',
+});
+```
+
+Exports: `@ssss/cli` / `@ssss/cli/engine` (Operation Contract engine),
+`@ssss/cli/bundle` (export/provision/import), `@ssss/cli/registry`,
+`@ssss/cli/runtime`, `@ssss/cli/frontmatter`.
+
+## Portability — why a vault is safe to sell
+
+| Class | Meaning | In a `sale` export? |
+|-------|---------|---------------------|
+| `structural` | The sellable business model (`workflow`, `rule`, `page`, …). | ✅ shipped |
+| `resource_bound` | Needs a real resource bound at provision (`domain`, `phone_number`). | ✅ shipped (as a parameter/step) |
+| `tenant_private` | The operator's private data (`task`, customer records). | ❌ **dropped** |
+
+`template` and `sale` exports MUST drop every `tenant_private` file. The reference
+bundle proves it — see `ssss help portability`.
+
+## Conformance
+
+A host MUST NOT claim SSSS conformance without passing the suite in
+[`conformance/`](conformance/):
+
+```bash
+ssss conformance            # structural + registry validation
+ssss conformance --engine   # + replay all fixtures + round-trip the reference bundle
+npm test                    # == ssss conformance --engine
+```
+
+## Repository layout
+
+```
+docs/ssss-spec.md          The normative specification (v0.6 draft).
+docs/help/                 Topic docs surfaced by `ssss help`.
+registry/core.json         14 document + 5 contract primitives; bundle & provisioning schemas.
+registry/extensions/       Application extension registries (e.g. festech).
+src/engine.mjs             Operation Contract engine (§6).
+src/runtime.mjs            Workflow trigger → event/task/run envelope planning (§11.8).
+src/bundle.mjs             export / validate / provision / import (§16–§17).
+src/registry.mjs           Registry-driven type + portability resolution.
+src/frontmatter.mjs        Zero-dependency YAML frontmatter.
+scripts/ssss.mjs           The `ssss` CLI dispatcher.
+conformance/               Canonical fixtures + reference bundle.
+```
+
+## License
+
+ISC © Greg Iteen. See [LICENSE](LICENSE).

package/VERSION

@@ -0,0 +1 @@
+0.7.0

package/conformance/README.md

@@ -0,0 +1,72 @@
+# SSSS Conformance
+
+This directory holds the **canonical conformance contract** for SSSS. It is the
+shared test suite every implementation MUST pass to claim conformance (spec §12).
+
+> A host MUST NOT claim SSSS conformance without passing the current fixture set.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| [`fixtures.json`](fixtures.json) | Canonical request/response fixtures for the Operation Contract (spec §6). |
+| [`reference-bundle.ucw.json`](reference-bundle.ucw.json) | The canonical `.ucw` reference bundle (spec §16, "Festival in a Box"). A `sale`-profile export, content-hashed; round-tripped by the runner. Rebuild with `node scripts/build-reference-bundle.mjs`. |
+| `../registry/core.json` | The 14 core document primitives + 5 contract primitives, plus the `runtime` (§11.8), `bundle` (§16), and `provisioning` (§17) schemas the standard owns. |
+
+## Implementations under test
+
+| Implementation | SSSS surface | Core primitives | Extensions |
+|----------------|--------------|-----------------|------------|
+| **festech.live** | `SsssOperationService` + `SsssLeaseService`, Postgres event log, ~4,024 vault files | all 14 ✓ | 118 app primitives |
+| **ultrachat** | SQL `ssss_core_contract` + hardening migrations, `SsssApiClient`, ~1,110 vault files | (audit pending) | app primitives |
+| **total-recall** | Markdown-native kernel, `validate-schema.mjs`, memory vault | memory-centric subset | memory categories |
+
+## How to run
+
+```bash
+npx ssss conformance              # structural + registry portability validation
+npx ssss conformance --engine     # also replay all fixtures + round-trip the reference bundle in-process
+npx ssss conformance --endpoint <url> --token <pat>   # run fixtures against a live host
+```
+
+The runner validates that the fixture file is well-formed and that every
+`expected_response` is internally consistent with the envelope rules. With
+`--engine`, it replays every fixture through the reference engine (`src/engine.mjs`)
+checks workflow runtime planning (`src/runtime.mjs`, spec §11.8), and round-trips
+the reference bundle (validate → provision → import → re-import, spec §16/§17)
+against a temp vault — proving idempotency and that no `tenant_private` file ever
+lands. With `--endpoint`, it POSTs each fixture's `request` to a host's Operation
+Contract endpoint and diffs the response.
+
+## Core vs. extension registry
+
+The standard owns only the **core**: the 14 document primitives and 5 contract
+primitives in [`../registry/core.json`](../registry/core.json), plus the `runtime`
+(§11.8), `bundle` (§16), and `provisioning` (§17) schemas. Every conformant
+implementation maps to the same core.
+
+Applications **extend** the core with their own primitives (festech has 118 —
+`meeting`, `phone_number`, `inventory_item`, `language_convention`, …). Extensions:
+
+- MUST NOT redefine or shadow a core type.
+- Live in the application's own extension registry, not here.
+- SHOULD follow the same schema shape as core entries (`required_fields`,
+  `append_only`, enums) so the same validator handles them.
+
+## ⚠️ Open reconciliation items (spec ⇄ implementation drift)
+
+These are real divergences found between the canonical spec and shipped
+implementations. Each needs a decision (amend the spec via §15, or fix the impl)
+before v1.0.
+
+| # | Item | Spec says | festech impl does | Proposed resolution |
+|---|------|-----------|-------------------|---------------------|
+| 1 | **`delete` envelope** | §6.2 defines only `operation`, `patch`, `event`. | Implements a 4th envelope type `delete` (remove a VFS file). | ✅ **Resolved (v0.3).** §6.2 now defines `delete` as the canonical 4th envelope; the reference engine and fixture-009 cover it. |
+| 2 | **Error codes** | §6.5 lists `401, 403, 409, 422, 500`. | Also returns `400` (invalid request / path traversal) and `404` (patch/delete target missing). | ✅ **Resolved.** §6.5 now lists `400` and `404` alongside the original five; `conformance/fixtures.json`'s `error_codes` block already documented all seven. |
+| 3 | **Registry source of truth** | §5 defines primitives in prose. | festech keeps a 131-entry `primitive-registry.json`; ultrachat encodes the contract in SQL migrations. | ✅ **Resolved.** Canonical machine-readable core now lives in `registry/core.json` + `registry/extensions/*`; the reference engine validates against it (registry-driven, no per-type code). Apps re-derive in Track F. |
+| 4 | **`language_convention` primitive** | Not in §5. §11.1 forbids translating control keys. | festech registers a `language_convention` primitive (multilingual authoring). | ✅ **Resolved (v0.4).** Documented in §11.7 as a `structural` presentation-overlay primitive (extension-owned). It never translates control keys — semantic-at-presentation, deterministic-at-validation. |
+
+The point of this directory: drift like the above is invisible when each app keeps
+its own copy of "the standard." Centralizing the fixtures + core registry here, and
+having all three implementations run against them, is what turns "SSSS is a
+standard" from a claim into a fact.