Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions .agents/skills/topo-archify-maintenance/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
name: topo-archify-maintenance
description: "Maintain the pinned Archify package and Topocode adapter with mandatory integration context and installed-artifact regression."
---

# Archify maintenance

Use only for authorized renderer/package maintenance, not ordinary story
authoring. **Before editing or updating anything**, read this entire skill and
[integration context](references/integration.md). Then read the selected
renderer package's `release.json` and `README.md`, Topocode's `archify-pin.json`,
and each source checkout's `AGENTS.md` plus contributing guidance. Recover the
actual source worktrees; installed consumer paths are not maintenance checkouts.
If context is missing, stop the update rather than infer a pin or prior decision.

1. Inspect upstream release notes and exact commit. Compare behavior, native
entrypoints, templates, fonts, schemas, output metadata, network activity and
provenance against the installed pin. Current main is not the selected runtime.
v3.0.1 is a known **unadopted** candidate because it changes update-check/
reminder behavior in deliver/finalize. Do not silently promote it.
2. Use owned isolated worktrees in `jdylanmc/topo-archify` and
`jdylanmc/topo-code`. Keep runtime bytes pristine. Inspect the fork's
`integrations/topo-npm/README.md` and `pack.mjs`. Preview the candidate with
`node integrations/topo-npm/update-pin.mjs <approved-full-commit>`.
After any required human approval, repeat with `--write`, then inspect the
`release.json` and `upstream-integrity.json` diff. This hashes the commit's
official ZIP entries, never edited local runtime bytes. Package versions are independent:
initially both public packages are 0.1.0, upstreamVersion is 3.0.0.
3. In the fork run:
`node integrations/topo-npm/pack.mjs dist` and
`node --test integrations/topo-npm/package.test.mjs`.
These are installed native/package checks, **not** the full upstream suite.
Run the selected revision's own `archify/package.json` test commands in
a matching separate checkout; report skipped/missing browser prerequisites.
4. In Topocode update the exact peer in `packages/diagram-core/package.json`,
the real dependency in `distribution/package.json`, `archify-pin.json` and
license inventory. Run `corepack yarn install`, then
`node scripts/bootstrap-renderer.mjs /path/to/candidate-renderer.tgz`.
This explicit local install needs no registry publication and writes no
file/resolution overrides. Refresh notices with `corepack yarn licenses:write`.
5. Run `TOPO_BROWSER_TEST_PORT=41875 corepack yarn test:regression`,
`node scripts/pack.mjs dist`, then
`node scripts/package-smoke.mjs dist/jdylanmc-topo-code-<version>.tgz /path/to/candidate-renderer.tgz`.
Use a different owned port if occupied; never kill another listener. Capture
browser evidence for all five families, exports, shared runtime/font handling
and the source-change repair journey. Keep failures visible; don't weaken
assertions, replace baselines blindly or raise timeouts to hide failures.
6. Return exact candidate commits/tarballs, upstream mapping, actual checks,
visual observations, failures and release blockers for independent review.
Passing compatible packaging/upstream patches may be merged/published by
agents under the owner's grant. **Ask the human** for minor/major upgrades,
runtime patches, or changed behavior/contracts even in a patch release.
Proposed runtime patches go upstream first; track any separately approved
patch and its upstream status explicitly.

No schedule, global skill install, credentials or first publication is implied.
The release owner verifies npm ownership and configured trusted-publisher access
(GitHub identity is insufficient). Publication is GitHub Actions only, through
each repository's `publish-npm.yml`, not local npm login/publish. Its manual
`mode` defaults to `verify`; normal publication uses `oidc`. Leave the npm
trusted-publisher Environment name blank; no GitHub environment is required.
Load the source checkout's `docs/npm-release.md` walkthrough before enabling it.
First-package bootstrap is explicit, not an OIDC fallback: the human sets
`NPM_BOOTSTRAP_TOKEN` through GitHub UI, and only the bootstrap publish step
receives it. Never request, read, echo or store the token. Parent-owned protected
tags `npm-bootstrap/v<version>-<reviewed-full-commit>` can trigger bootstrap
before default-branch dispatch is available; version, commit, creation event
and complete gates must match. No arbitrary branch push, tag update, schedule
or auto-merge is authorized. Have the human revoke the token and delete repository secrets
after the first versions. Do not claim npm trust or publication from workflow
preparation alone.
Publish the tested renderer first, then verify the public renderer dependency
and publish Topocode from its hosted workflow.
Never claim a package is published merely because packing or installation passed.
75 changes: 75 additions & 0 deletions .agents/skills/topo-archify-maintenance/references/integration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Integration facts that an update must retain

This is the durable context, not a replacement for inspecting current code.
Original decisions: Topocode issues #41 (renderer) and #13 (distribution),
https://github.com/jdylanmc/topo-code/issues/41 and
https://github.com/jdylanmc/topo-code/issues/13.

## Pin and boundary

- Initial renderer package `@jdylanmc/[email protected]` contains upstream
**3.0.0**, commit `9286c3b9c2cef359e98586b420d769d87bcb163f`, official
`archify.zip` SHA-256
`e30f65ddab8bbb0c467fa4be5bccf7e3853bd3ee86e8338f31e102037496be18`.
All **104** files are pristine. No runtime patches or install hooks.
- The fork distributes the official archive behind a narrow filesystem API:
`runtimeDirectory`, `cliPath`, `architectureRendererPath`,
`outputCheckerPath`, `verifyRuntime`. It is not a general public SDK.
- Topocode alone owns story semantics, source grounding, typography/narrative
adaptation, catalogue/navigation, shared assets and bundle behavior through
`@topo/diagram-core`. Private modules are bundled implementation details.
Do not import the unrelated npm package `archify`.
- Former checked-in integrity baselines remain under
`packages/diagram-core/integrity/`. They are historical evidence, not license
to rewrite the pin when edited bytes fail. MIT, third-party, embedded
JetBrains Mono SIL OFL 1.1, brand and trademark notices stay verbatim.
- Upstream main already moved to **3.0.1**, adding automatic update-check/reminder
behavior in deliver/finalize. Initial packaging intentionally keeps 3.0.0.
Inspect network/local-first behavior before proposing adoption.

## Compatibility lessons and regression oracles

- **Output isolation:** v3 requires portable `meta.output`. Supply it only in
generated renderer input, never authored `.topo.json`. Execute in an owned
temporary working directory so an unrelated caller's `story.html`, including
a symlink, cannot influence output-path validation.
- **Lifecycle:** preserve compatible native v1 geometry. State dimensions and
column/route gaps use final typography, including cross-platform glyph
containment and a **12px effective text floor**. The failed smaller native
sizes and insufficient route clearance were repaired in the adapter, not by
patching pristine renderers or reducing the floor.
- **PNG framing:** v3 native PNG is a title/card frame around a uniformly scaled
diagram. Canonical SVG remains bare geometry. Compare inner geometry and
meaning; do not force the old whole-image aspect ratio by cropping or stretching.
- **Shared runtime/export fonts:** repository pages share runtime assets but
must keep ID-addressed font style text, document JSON and context-sensitive
markup. Native SVG/PNG exports read these DOM values. Externalizing the font
style without preserving its text breaks exports even when preview looks fine.
- **Bounded batches:** architecture pages run native renderer and output checker
in bounded child batches with staged files; do not retain all standalone HTML
strings or introduce unbounded worker lifetimes.
- **Provenance:** native deliver receipts bind pre-adaptation bytes. Typography,
narratives and shared-asset transforms change those bytes. Never advertise
upstream finalize certification/hash for consumer-transformed artifacts.
- **Authoring:** structural validation and resolved anchors are objective evidence,
not semantic truth. The installed tarball fixture must move source, observe
stale-anchor failure, repair only affected fields, preserve stable IDs and
unrelated intent, then preview and bundle.

## Where the executable evidence lives

In Topocode: `packages/diagram-core/test/diagram-core.test.mjs` (pin, native
families, isolation and tamper), `packages/cli/src/viewer-assets.test.ts` (shared
assets), `packages/cli/src/story-authoring.test.ts` (source-change loop),
`packages/site/tests/` (native browser behavior), `scripts/package-smoke.mjs`
(installed consumer journey). Run the entire `test:regression` gate; filenames
are navigation hints, not a reason to narrow out another affected contract.

In the fork: `integrations/topo-npm/package.test.mjs` verifies the actual packed
inventory, clean npm install, exported paths, native families, notices and
tamper failures. Selected-runtime smoke is distinct from a complete upstream
suite at its matching revision. Report both honestly.

There is no cross-machine reproducibility or manual visual-review claim from
a single local run. The distribution changes ownership of runtime packaging,
not the meaning of authored stories or upstream certification.
45 changes: 36 additions & 9 deletions .agents/skills/topo-story-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ invoke a hosted model service, and do not add model execution to `topo scan`.
## Create or update the authored story

Write the durable document under `stories/**/*.topo.json` using
`@topo/story/story.schema.json`. Keep authored documents outside `.topo/cache/`;
`node_modules/@jdylanmc/topo-code/story.schema.json` (or the same exported
`@jdylanmc/topo-code/story.schema.json` from a global installation).
Keep authored documents outside `.topo/cache/`;
that directory contains generated output and is never the editing surface.

For a new story, choose one stable lowercase `id`, a focused title and summary,
Expand All @@ -30,8 +32,7 @@ authored document.
Validate the uncommitted draft against the current working tree:

```sh
corepack yarn topo story validate /absolute/path/to/repository \
/absolute/path/to/repository/stories/example.topo.json
npm exec --no -- topo story validate . stories/example.topo.json
```

Repair each reported `invalid-document`, `missing-file`, `missing-symbol`, or
Expand All @@ -45,16 +46,42 @@ Commit the source and authored story together. Build or refresh the generated
site, preview the committed story, and inspect it locally:

```sh
corepack yarn topo scan /absolute/path/to/repository
corepack yarn topo story preview /absolute/path/to/repository \
/absolute/path/to/repository/stories/example.topo.json
corepack yarn topo serve /absolute/path/to/repository
npm exec --no -- topo scan .
npm exec --no -- topo story preview . stories/example.topo.json
npm exec --no -- topo serve .
```

Open `/stories/<story-id>/`. If source changes later, rerun validation before
previewing and preserve identity plus unrelated authored intent during repairs.
Humans review the authored explanation and generated view; they do not edit the
renderer output in `.topo/cache/site`.

The executable before/after example and expected evidence are documented in
[`docs/story-authoring.md`](../../../docs/story-authoring.md).
Commit only when authorized by the repository owner. For a globally installed
CLI, use `topo` directly instead of `npm exec --no -- topo`.

## Minimal source-grounded document

Read the actual source before adapting this example. `symbol` names a compiler
declaration; `pattern` is an exact text match within the file. Anchors store
neither derived line numbers nor renderer-specific data.

```json
{
"schemaVersion": "1.0",
"id": "request",
"title": "Request handling",
"summary": "A focused explanation verified against the source.",
"anchors": [{"id": "handler", "path": "src/handler.ts", "symbol": "handle"}],
"sections": [{"id": "handle", "title": "Handle request", "body": "Describe the observed behavior.", "anchorIds": ["handler"]}],
"connections": []
}
```

Architecture is the default; `diagramFamily` also accepts `workflow`, `sequence`,
`dataflow` and `lifecycle`. Every source-grounded section needs evidence. Use
`classification: "capability-demo"` only for explicitly conceptual, anchor-free
renderer demonstrations, never to bypass missing factual evidence. Prefer
small focused stories and short labels. For source moves, reread both sides,
repair only affected anchors and explanation, and retain IDs/unrelated intent.
The package includes executable before/after fixtures under
`node_modules/@jdylanmc/topo-code/examples/story-authoring/`.
37 changes: 37 additions & 0 deletions .agents/skills/topo/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
name: topo
description: "Initialize and operate a local Topocode repository storybook with the installed CLI."
---

# Topocode project toolbelt

Requires Node 22+, Git and `@jdylanmc/topo-code` installed in this repository.
Run `npm exec --no -- topo --help`; `--no` prevents an accidental package download.
For a global installation, `topo` is equivalent. No Topocode source checkout,
Corepack, model service, account or renderer download is needed.

1. Inspect source, current Git state, existing stories and `.topo/config.json`.
Use `npm exec --no -- topo init . --skills` for opt-in project context.
Identical context files are preserved; differing files and symlinks fail
explicitly. Do not overwrite existing skills/instructions or use a force flag.
Without `--skills`, init only initializes the workspace.
2. Run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders
committed stories plus Repository exploration. It never invokes a model.
Unsupported/unresolved source fails; an explicitly requested `--allow-partial`
preview is visibly partial and exits 2, not success.
3. Read [story authoring](../topo-story-authoring/SKILL.md). Author/refine a focused
explanation from source evidence. Validate drafts; commit only with the
repository owner's authority, then scan/preview the committed story.
4. Run `npm exec --no -- topo serve . --port 4173`. Review the printed loopback
URL: Repository canvas, story navigation, source evidence, theme and exports.
Stop your server when finished; never kill another user's listener.
5. Run `npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/`.
Serve the output with a static server. Hosting, access control and uploading
are separate owner decisions. Preserve all emitted license notices.

`topo enrich` is a separate, explicitly configured provider-command workflow for
secondary commentary. It is not required for source-grounded story editing.
Never execute an unknown enrichment command or claim inferred commentary is fact.
Do not edit generated `.topo/cache` artifacts. Keep story IDs stable when source
moves. [Renderer maintenance](../topo-archify-maintenance/SKILL.md) is a maintainer
workflow, not an automatic consumer update or global skill installation.
33 changes: 30 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,41 @@ permissions:
jobs:
check:
runs-on: ubuntu-latest
defaults:
run:
working-directory: topocode
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
node-version-file: .node-version
path: topocode
- name: Check out the reviewed renderer packaging source
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
repository: jdylanmc/topo-archify
ref: b94790e99e2ca51fcdb74a9bd0f10f637856f92f
path: renderer
fetch-depth: 0
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version-file: topocode/.node-version
- run: corepack enable
- run: yarn install --immutable
- name: Build and verify the pinned renderer package
run: |
node --test ../renderer/integrations/topo-npm/package.test.mjs
node ../renderer/integrations/topo-npm/pack.mjs ../renderer/dist
node scripts/bootstrap-renderer.mjs ../renderer/dist/jdylanmc-topo-archify-0.1.0.tgz
- name: ESLint correctness baseline
run: yarn lint
- run: yarn workspace @topo/site exec playwright install --with-deps chromium
- run: yarn test:regression
- name: Verify the installed public toolbelt
run: |
node scripts/pack.mjs dist
node scripts/package-smoke.mjs dist/jdylanmc-topo-code-0.1.0.tgz ../renderer/dist/jdylanmc-topo-archify-0.1.0.tgz
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: npm-candidates
path: |
topocode/dist/*.tgz
renderer/dist/*.tgz
Loading
Loading