@structor-dev/cli 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are 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.2.0] - 2026-06-03
+
+### Added
+
+- `structor doctor` diagnostics for generated workspaces and consumer pointers.
+- Structor contributor bootstrap support, including the self-harness preset,
+  setup command, and contributor smoke checks.
+- Passive generation manifests for generated harnesses.
+- Public onboarding, contributor setup, example, and launch-positioning docs.
+
+### Changed
+
+- `structor init` now defaults the generate-harness confirmation to yes after
+  previewing the planned writes.
+- Generated harness templates now include stronger governance, workspace,
+  validation, and cockpit surfaces.
+
+### Fixed
+
+- Hardened generated writes, consumer entrypoints, symlink handling, generated
+  JavaScript/Markdown escaping, shell-quoted worktree repair commands, and
+  validator provenance checks.
+- Centralized config resolution, rendered template values, generated harness
+  contracts, and generated-path safety checks.
+
+## [0.1.0] - 2026-05-29
+
+Initial experimental release of the `@structor-dev/cli` harness generator.
+
+### Added
+
+- `structor init` guided, local-only, deterministic workspace setup with sibling
+  consumer-repo detection, config preview, and dry-run before any writes.
+- `structor generate` to render a harness from an existing `harness.config.json`,
+  with `--dry-run`, `--force`, `--install-consumer-entrypoints`, and safe
+  output-path enforcement.
+- Versioned harness template covering context routing (`ai/HUB.md`), contracts,
+  task templates, review skills, quality tracking, and decisions.
+- Codex and Claude Code client surfaces gated by `models` and `clientSupport`
+  config, including Codex hook scaffolding and Claude project rules.
+- Mechanical validators: config-shape, template-file, task-template,
+  contract-manifest, model-overlay, and placeholder-leak checks, plus a smoke
+  test that generates and bootstraps disposable workspaces.
+
+### Notes
+
+- `structor doctor` is planned but not yet implemented.
+- Claude hooks and Claude skills are deferred; keep those flags off until
+  fixture-backed validators exist.

package/README.md

@@ -3,13 +3,45 @@
 > Experimental. Early infrastructure for harness engineering. The API,
 > generated layout, and config shape may change.
 
-Structor generates a repository-local AI engineering harness for your project:
-a versioned policy layer that gives Codex, Claude Code, and similar agents a
-shared, enforceable set of rules for context routing, contracts, task shape,
-review, and validation.
+Structor is a local harness-engineering toolkit. It generates a
+repository-local AI engineering harness for your project: a versioned policy
+layer that gives Codex, Claude Code, and similar agents a shared, enforceable
+set of rules for context routing, contracts, task shape, review, and
+validation.
 
 It is a generator, not a runtime. Structor scaffolds the harness; it never runs
 agents, polls sessions, automates pull requests, or touches external services.
+The open-source generator is local-only: no telemetry, no LLM calls, and no
+network calls during `init` or `generate`.
+
+Structor is for teams that want agent guidance to live next to their code,
+review history, and validation commands instead of in scattered chat prompts.
+It is useful when a project has multiple repos, multiple agent clients, or
+repeatable review and validation expectations that should be checked
+mechanically.
+
+Structor is MIT-licensed so teams can generate, modify, and use harness
+artifacts inside private or commercial repositories. Commercial policy packs,
+private templates, tailored rollout support, or hosted services may be licensed
+separately.
+
+## First Minute
+
+- **What it is:** a local generator for repository-local AI engineering
+  harnesses.
+- **Who it is for:** teams that want Codex, Claude Code, and similar agents to
+  share reviewed project policy, task shape, and validation expectations.
+- **Why not just a rules file:** Structor gives the rules a repeatable
+  generated structure, thin client entrypoints, and validators that catch drift.
+- **What it creates:** a sibling harness repo with canonical `ai/*` policy,
+  Codex and Claude entrypoints, contracts, task templates, review guidance, and
+  local validation scripts.
+- **What it does not do:** run agents, coordinate sessions, open pull requests,
+  host services, call LLM APIs, install packages, or mutate external systems.
+- **How to try it:** run `npx @structor-dev/cli init` from the workspace folder
+  that contains your consumer repos.
+- **How validation is split:** `npm run check:ci` is the fast structural path;
+  `npm run validate` adds tests and smoke-tested generated-harness flows.
 
 ## Quick Start
 
@@ -23,8 +55,14 @@ During local development from a clone of this repo, use
 `node ./structor/bin/structor.mjs init` from the parent workspace instead.
 
 `init` is local-only and deterministic. It detects sibling repos, asks a few
-questions, previews every file it would write, and generates nothing until you
-confirm. No network calls, no LLM calls, no installs.
+questions, writes `harness.config.json` only after confirmation, previews every
+generated file with a dry run, and generates nothing until you confirm. No
+network calls, no LLM calls, no telemetry, no package installs, and no remote
+service mutation.
+
+`structor init` remains the normal setup flow for users creating generated
+harnesses for their own target repositories. Contributing to Structor itself is
+a separate workflow.
 
 ## What You Get
 
@@ -50,6 +88,18 @@ scripts/            validation that mechanically enforces the rules above
 Optional consumer repo pointer files can route agents back to the generated
 harness from each code repo.
 
+## Why Not Just Use A Rules File?
+
+A single `AGENTS.md`, `CLAUDE.md`, or prompt file can tell an agent what to do,
+but it cannot easily keep project facts, model-specific overlays, contracts,
+task templates, review guidance, and validation policy synchronized across a
+workspace.
+
+Structor keeps canonical policy in the generated harness, keeps consumer
+entrypoints thin, and ships validators that check the structure. The result is
+still plain files in your repository; Structor just gives those files a stable
+shape and a way to detect drift.
+
 ## Why It Exists
 
 Most AI coding workflow tooling is a pile of prompts and rules with nothing
@@ -58,7 +108,7 @@ context architecture plus mechanical enforcement. The generated harness ships
 with validators that fail when policy drifts: overlay drift checks, contract
 manifest checks, task-shape checks, and hook guardrails.
 
-## Manual Setup
+## Conservative Manual Path
 
 If you prefer the conservative manual path, create `harness.config.json` and
 run:
@@ -71,6 +121,17 @@ npx @structor-dev/cli generate --config harness.config.json --install-consumer-e
 See `docs/INIT.md` for the exact safety model, read/write behavior, and
 recovery expectations.
 
+## How Structor Differs From A Runner
+
+Structor creates files and validation scripts. A runner executes or coordinates
+agent work over time.
+
+Structor does not start agent sessions, poll threads, assign tasks, open pull
+requests, shepherd CI, auto-repair code, merge branches, or host dashboards.
+Those behaviors belong in a separate runner or orchestration layer. Generated
+Codex hooks are local policy guardrails only; they are not a general execution
+runtime or a complete security boundary.
+
 ## Codex And Claude Support
 
 Structor uses a hybrid model for client support:
@@ -142,6 +203,8 @@ These boundaries are intentional in the current template:
 - Claude skills are deferred. Keep `clientSupport.claude.skills` false or omit
   it until committed `.claude/skills/*/SKILL.md` templates and validation are
   added.
+- Read-only generated Harness Cockpit views under `ai/views/*` are allowed
+  when they are derived from canonical local files and do not execute workflows.
 - The initializer creates a repo-shaped harness folder, but it does not run
   `git init`, create remotes, install dependencies, publish branches, or modify
   external services.
@@ -150,9 +213,9 @@ These boundaries are intentional in the current template:
   The generated workspace
   bootstrap script installs workspace-level pointers and verifies consumer
   routing; it does not repair missing consumer pointers after initialization.
-- Runner behavior remains out of scope. Polling, PR automation, dashboards,
-  auto-merge, repair loops, and CI shepherding belong in a separate runner or
-  orchestration layer.
+- Runner behavior remains out of scope. Polling, PR automation, live
+  dashboards, auto-merge, repair loops, and CI shepherding belong in a separate
+  runner or orchestration layer.
 
 ## Out-of-the-Box Flow
 
@@ -225,6 +288,8 @@ Rules:
   templates.
 - Create or update harness.config.json for this workspace.
 - Set output.path so the generated harness repo is a sibling of the consumer repos.
+- Set consumer paths as workspace-relative sibling paths such as `./project-app`;
+  do not use absolute paths or `..` traversal.
 - Use concrete template-provided client-support files. Do not invent Codex or
   Claude Code surfaces from scratch.
 - If customizing Codex hook rules, keep them deterministic, local, read-only,
@@ -259,8 +324,8 @@ require human input.
 
 ## Manual Setup
 
-Use these commands when you want to operate the template without an
-agent-assisted prompt.
+Use these commands from this template repo when you want to operate the
+template without an agent-assisted prompt.
 
 Copy and edit the example config:
 
@@ -277,7 +342,10 @@ Set:
 - optional `clientSupport.codex.hooks`
 - optional `clientSupport.claude.rules`; keep `clientSupport.claude.hooks` and
   `clientSupport.claude.skills` false or omitted until those surfaces are added
-- each consumer `name`, sibling `path`, `purpose`, and validation commands
+- each consumer `name`, workspace-relative sibling `path`, `purpose`, and
+  validation commands. Consumer paths must stay inside the workspace and cannot
+  use absolute paths or `..` traversal. From a template clone at
+  `workspace/structor`, use paths like `./project-app`, not `../project-app`.
 
 Validate the template and config shape:
 
@@ -362,14 +430,26 @@ npm run check:ci
 npm run validate
 ```
 
-`npm run check:ci` covers the cheap structural checks that feed both local
-development and CI: config examples, required template files, task template
-structure, contract manifest schema, placeholder hygiene, and model overlay
-thinness.
+Validation is split into fast structural checks and the full local smoke suite.
+
+`npm run check:ci` covers the cheap checks that feed both local development and
+CI: config examples, active shipped schemas, required template files, task
+template structure, contract manifest schema, placeholder hygiene,
+public-release hygiene, and model overlay thinness.
+
+The active shipped schemas are `schemas/harness-config.schema.json` and
+`schemas/contract-manifest.schema.json`. Task brief validation is intentionally
+Markdown/template based through `scripts/check-task-template.mjs`, not a shipped
+JSON Schema contract.
+
+Generated harness files are declared in `scripts/generated-harness-contract.mjs`.
+That contract is the source of truth for render gates, trusted generated
+scripts, validation check dependencies, workspace-required files, and
+consumer/workspace entrypoint participation.
 
-The placeholder check has no hardcoded private project names. If you are
-extracting a harness from a private codebase, opt into leak detection with a
-comma-separated list:
+The placeholder and public hygiene checks have no hardcoded private project
+names. If you are extracting a harness from a private codebase, opt into leak
+detection with a comma-separated list:
 
 ```sh
 HARNESS_FORBIDDEN_PROJECT_TERMS="Internal Product,private-api" npm run check:placeholders
@@ -395,11 +475,41 @@ For a real project config, require configured consumer repo paths to exist:
 node scripts/check-config.mjs --config harness.config.json --require-existing-consumers
 ```
 
+## Structor Contributor Model
+
+The recommended Structor contributor path should become:
+
+```sh
+npx @structor-dev/cli contribute structor
+```
+
+That future contributor bootstrap creates or refreshes a contributor workspace:
+a local Structor source checkout plus a sibling Structor self-harness whose
+consumer repository is Structor itself. The self-harness is repo-local guidance
+for working on Structor; it does not change the generic generated harness model
+for other projects.
+
+The contributor bootstrap may clone local repositories when preparing that
+workspace, but v1 must not fork repositories, push branches, open pull requests,
+mutate GitHub or other external services, run agents, or become a runner.
+
+The manual contributor setup path remains the clone-first fallback:
+
+```sh
+git clone https://github.com/nicolaycamacho/structor.git
+cd structor
+npm run setup:contributor
+```
+
 ## Non-Goals
 
 - No runner or orchestration runtime.
 - No Linear, GitHub, Claude hook, or CI automation.
 - No Codex runner automation beyond local harness hook guardrails.
-- No dashboards, polling loops, session control, auto-merge, or repair daemons.
+- No live dashboards, polling loops, session control, auto-merge, repair
+  daemons, or orchestration UI.
+- Read-only generated Harness Cockpit views are allowed when they summarize
+  canonical local files and do not execute validation, mutate state, or control
+  workflows.
 - No consumer implementation logic.
 - No source-project or other project-specific content in active templates.

package/ROADMAP.md

@@ -0,0 +1,38 @@
+# Roadmap
+
+Structor is a harness-engineering toolkit for generating repository-local AI
+engineering harnesses. It is a local generator, not a runner or hosted product.
+
+## Current Open-Source Core
+
+- Local `init` and `generate` flows for repository-local harnesses.
+- Deterministic templates for Codex and Claude Code guidance.
+- Conservative path, template, schema, and governance validation.
+- Optional local consumer entrypoint installation.
+- MIT licensing so teams can generate, modify, and use harness artifacts inside
+  private or commercial repositories.
+
+## Near-Term Launch Readiness
+
+- Keep public documentation clear about local-only behavior and non-goals.
+- Add small, deterministic public-release hygiene checks.
+- Improve contributor setup for Structor itself without turning it into a
+  runner or workflow orchestrator.
+- Keep examples and documentation focused on harness generation and validation.
+
+## Future Possibilities
+
+- Commercial policy packs, private templates, tailored rollout support, or
+  hosted services may be licensed separately.
+- Deeper consumer-repo scan and review flows may help teams draft
+  project-specific harness content from local evidence.
+- Diagnostic tooling may help users inspect existing harness workspaces for
+  drift, stale pointers, and validation gaps.
+
+## Non-Goals
+
+- No agent runner, polling loop, dashboard, auto-merge system, or repair daemon.
+- No telemetry, LLM calls, external service mutation, or hosted workflow in the
+  open-source generator.
+- No consumer implementation logic or deployment automation.
+- No license change away from MIT in this launch slice.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Reporting A Vulnerability
+
+Please do not disclose exploit details publicly before the issue has been
+reviewed.
+
+If GitHub private vulnerability reporting is available for this repository,
+please use it first. Otherwise, open a minimal public issue that says you have a
+security report to share, but leave exploit details, proof-of-concept payloads,
+tokens, private paths, and affected private repositories out of the issue body.
+
+This is a solo-maintainer project. Security reports are handled on a
+best-effort basis, without a formal response-time or fix-time SLA.
+
+## Scope
+
+Structor is a local generator for repository-local AI engineering harnesses. It
+does not run agents, host services, collect telemetry, poll sessions, automate
+pull requests, or mutate external services.
+
+Security-sensitive areas include:
+
+- Generated script templates and render gates.
+- Path validation for consumer repositories and generated harness output.
+- Generated agent entrypoints, hook guardrails, and validation scripts.
+- Public release hygiene that prevents accidental private-project leakage.
+
+## Supported Versions
+
+Structor is experimental and early. Please report suspected vulnerabilities
+against the current `main` branch unless a release-specific issue is clearly
+involved.