Files
pipelines/scripts/smoke-first-install.py
T
alan a3f571d672 docs: make docs-fold the single writer of shared documentation
Every item wrote the shared, append-only docs (android/README.md, docs/cli.md and
the packaged skill references), so every merge conflicted on prose. Keep the duty
to notice stale docs; move the writing to one deliberate place.

- Per-item note, not a shared edit. An item that makes a shared document stale
  writes docs/notes/<slug>.md - unique per item, so two items never touch the same
  file - and commits that note with its change. It never edits a README, topic doc
  or packaged skill reference itself.
- One writer. The manual-only docs-fold pipeline, bundled as the fifth starter
  examples/docs-fold.md, folds every note under docs/notes/ into the shared
  document it names and deletes the consumed notes in its own commit; an empty
  notes directory is a success no-op. Operator trigger:
  pipelines new "Docs fold" --template docs-fold --no-open; pipelines submit
  <draft.md>; pipelines run "Docs fold".
- Implemented where the convention lives: orchestration.md (brief item 5, the
  hard-constraint bullet, a "Single documentation writer" section and the
  "Pipeline choice" committer bullet), the canonical committer checklist in
  format.md (new step 6), the committer prompts in examples/task.md and
  examples/three-stage.md, the new examples/docs-fold.md with its catalog and
  README entries, and the repository guideline AGENTS.md. Test-expectation counts
  (examples/catalog_test.go, internal/server/templates_test.go,
  scripts/smoke-first-install.py) follow the fifth starter.

Reflected where it belongs: the packaged templates (examples/task.md,
examples/three-stage.md, the new examples/docs-fold.md), the packaged skill
references (orchestration.md, format.md) and the repo guideline AGENTS.md all carry
the new convention. No new reference file was added, so install.go's managed
inventory is unchanged. The shared descriptive docs were deliberately not
rewritten: this change makes README.md:191, docs/cli.md:170 and
internal/author/skill/references/operations.md:13 name four starters where there are
now five. Those stay as they are - correcting them now is exactly the per-item
shared edit this change removes - and the stale-doc note
docs/notes/docs-fold-single-writer.md records each one for the docs-fold writer to
fold. Nothing else needed updating. No new dependency; no Android, Gradle, server,
installer, Docker or published-definition change; no definition published over the
running pipelines.

Evidence: go test -count=1 ./... passed; go build ./... and go vet on the touched
packages clean; ./internal/author/... covers embedding, reference links, the managed
inventory and install/upgrade/protection; ./examples/... validates the fifth starter
and its manual-only, committer-terminated graph; ./internal/server/... covers the
served catalog. Not run: the docs-fold writer against the shared docs (nothing to
fold yet); no install or deploy.

(cherry picked from commit f29656cf084d7eee2e033f2a37a9d231d7acaaf0)
2026-10-17 23:59:59 +01:00

108 lines
5.1 KiB
Python

#!/usr/bin/env python3
"""Developer-only source lifecycle check; not an alternative installer. No inference."""
import argparse
import json
import os
from pathlib import Path
import socket
import subprocess
import tempfile
import time
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--temp-dir", help="Parent directory for disposable test files")
args = parser.parse_args()
repo = Path(__file__).resolve().parent.parent
with tempfile.TemporaryDirectory(prefix="pipelines-first-install-", dir=args.temp_dir) as temporary:
root = Path(temporary)
env = {k: v for k, v in os.environ.items() if not k.startswith("PIPELINES_")}
env.update(GOBIN=str(root / "bin"), XDG_CONFIG_HOME=str(root / "config"),
XDG_DATA_HOME=str(root / "data"), PIPELINES_DRAFT_DIR=str(root / "drafts"))
subprocess.run(["go", "install", "-trimpath", "./cmd/..."], cwd=repo, env=env, check=True, timeout=180)
subprocess.run([str(root / "bin/pipelines"), "skill", "install"], cwd=repo, env=env, check=True, timeout=30)
cli = root / "bin/pipelines"
assert (root / "bin/pipelines-tui").is_file(), "TUI binary missing"
assert (root / "config/opencode/skills/pipelines/references/operations.md").is_file(), "Skill not installed"
workspace = root / "workspace"
workspace.mkdir()
def local(*command):
return subprocess.run([str(cli), *command], cwd=workspace, env=env,
capture_output=True, text=True, check=True, timeout=30).stdout
version = json.loads(local("version", "--json"))
assert version == json.loads(local("--version", "--json"))
assert "import [FILE.zip]" in local("help")
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
port = sock.getsockname()[1]
endpoint = f"ws://127.0.0.1:{port}/connect"
database = root / "runs.db"
def rpc(*command):
return json.loads(local("--url", endpoint, *command, "--json"))
def start(log):
process = subprocess.Popen([str(root / "bin/pipelines-server"), "-addr", f"127.0.0.1:{port}",
"-db", str(database)], cwd=workspace, env=env, stdout=log, stderr=log)
try:
deadline = time.monotonic() + 15
while time.monotonic() < deadline:
if process.poll() is not None:
raise RuntimeError("Test server exited; see " + str(root / "server.log"))
try:
with socket.create_connection(("127.0.0.1", port), timeout=.1):
return process
except OSError:
time.sleep(.05)
raise RuntimeError("Test server did not become ready")
except BaseException:
stop(process)
raise
def stop(process):
process.terminate()
try:
process.wait(timeout=10)
except subprocess.TimeoutExpired:
process.kill()
process.wait()
raise
with (root / "server.log").open("w") as log:
process = start(log)
try:
pong = rpc("ping")
assert pong["build"] == version, "Client/server build mismatch"
assert not rpc("list").get("pipelines"), "Fresh database must be empty"
assert not rpc("runs").get("runs"), "Fresh database must have no runs"
assert len(rpc("templates")["templates"]) == 5
draft = rpc("new", "First test", "Review the repository", "--template", "review", "--no-open", "--yes")
assert not rpc("list").get("pipelines"), "Draft creation must not publish"
rpc("validate", draft["path"])
rpc("submit", draft["path"], "--yes")
published = rpc("show", "First test")
assert published["version"] == 1
archive = root / "definitions.zip"
rpc("export", "First test", "--output", str(archive))
result = rpc("import", str(archive), "--all", "--yes")
assert not result["imported"], "Identical import must not republish"
assert rpc("show", "First test")["version"] == 1
assert Path(draft["path"]).is_file(), "Published draft must remain"
finally:
stop(process)
process = start(log)
try:
assert rpc("show", "First test")["source"] == published["source"], "Definition lost on restart"
assert rpc("ping")["build"] == version
assert not rpc("runs").get("runs"), "Smoke check must not execute a workflow"
finally:
stop(process)
print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, five templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.")
if __name__ == "__main__":
main()