Skip to content

v0.2.0

Choose a tag to compare

View all tags
@lair001 lair001 released this 23 Aug 00:19
· 39 commits to main since this release
v0.2.0
ec68c0d

Theme Forge Stellar Burst v0.2.0

Theme Forge Stellar Burst (TFSB) v0.2.0 expands from an initial compiler into a complete lifecycle management system for vector assets. It introduces safe upstream archive reconciliation with paired-checkpoint provenance, deterministic bundle export/import, semantic multi-baseline diffing, canonical formatting, static offline visual preview galleries, versioned JSON machine automation, and relocatable v3 build receipts.

Highlights

  • Safe Incremental Reconciliation (tfsb reconcile):
    Reconcile upstream ZIP archives safely against paired-checkpoint provenance (.tfsb/provenance.json). Reconcile is read-only by default (--dry-run), never deletes omitted assets silently (turning them into accepted tombstones), and requires explicit per-record authority (--resolve, --rename, --rename-companion, --remove, --remove-companion) for conflicts, renames, and deletions. Commits via atomic transactional swap (--apply).

  • Deterministic Bundle Export & Manifest Import (tfsb bundle, tfsb import --manifest):
    Export canonical vector assets and companions as store-only (level 0), deterministic ZIP bundles containing tfsb-manifest.json with cryptographic SHA-256 digests. Manifest-assisted import preserves declared asset IDs and file names across environments without leaking private install destinations or provenance history.

  • Semantic Multi-Baseline Diffing (tfsb diff):
    Compare canonical .tfsb semantics against four operational baselines: --provenance (default), --archive <file.zip>, --build, and --install. Uses the frozen tfsb-path-text-v1 digest for granular path comparisons and exits 0 (clean), 2 (valid semantic difference), or 1 (invalid/unavailable baseline).

  • Canonical Formatter (tfsb fmt):
    Canonically format .tfsb/project.toml and .tfsb/assets/*.toml with deterministic whitespace and key layout in a single whole-tree transaction. Non-destructive --check mode exits 2 when formatting differences exist.

  • Offline Static Preview Gallery (tfsb preview):
    Generate an offline, scriptless, fully escaped HTML/CSS asset gallery in .tfsb-preview. Renders directly from canonical TOML models across multiple responsive sizes (16px to 256px) and displays build/install drift badges without requiring an HTTP server or JavaScript.

  • Versioned JSON Machine Results (--json):
    All inspection and lifecycle query commands (check, list, reconcile, diff, bundle, fmt, preview) emit a single schema-version-1 JSON envelope with deterministic key order for script and CI/CD integration.

  • Relocatable v3 Build Receipts:
    Emits tfsb-build-v3 receipts tracking normalized project install policy evidence alongside build output hashes. Transparently accepts existing tfsb-build-v2 receipts for check, build, and install, upgrading them on the next build.

  • Terminal Nova Qualification:
    Fully qualified against the production asset corpus of Theme Forge Terminal Nova across multi-browser visual baselines (Chromium, Firefox, WebKit).

Upgrading from v0.1.0

Upgrading from v0.1.0 is seamless and backward-compatible:

  1. Provenance Bootstrap:
    To establish paired-checkpoint provenance for an existing project, run tfsb reconcile <matching-archive.zip> --apply using an archive that matches your current canonical assets. If the archive differs, provide explicit resolution flags (--resolve, --rename, --remove).

  2. Build Receipt Upgrade:
    Existing tfsb-build-v2 receipts continue to serve as valid build ownership evidence for tfsb check, tfsb build, and tfsb install. Run tfsb build once to upgrade to a tfsb-build-v3 receipt with project policy evidence, which unlocks tfsb diff --build.

  3. Preview Directory:
    The .tfsb-preview gallery directory is generated output and should be added to .gitignore.

Scope and Boundaries

  • Runtime: Requires Node.js >=22.0.0.
  • Bounded SVG Profile: Supports a safe declarative subset (paths, groups, linear gradients, use references, accessibility tags). Arbitrary scripts, CSS <style> blocks, external resources, foreign objects, animations, and non-linear gradients fail closed.
  • Local Archives Only: All import, reconcile, diff, and bundle operations operate strictly on local filesystem ZIP archives; remote network downloads are excluded.
  • Companion Documents: Preserves explicitly selected text documentation (*.md, *.markdown, *.txt) and well-known legal documents (LICENSE, NOTICE, COPYING, COPYRIGHT) byte-for-byte. Executable scripts and code files fail closed.
  • Limits: Max 1,024 archive entries, max 128 selected/mutating SVG assets, 8 MiB per selected entry, 32 MiB aggregate selected bytes, and 128 MiB raw archive size. Full external icon warehouses are not a v0.2 lifecycle target.

Installation

npm install --global @knowledge-forge-ai/theme-forge-stellar-burst@0.2.0

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). Commercial licensing options are available for proprietary terms (COMMERCIAL-LICENSE.md).

Assets 2
Loading