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
7 changes: 4 additions & 3 deletions .agents/skills/topo/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,10 @@ Corepack, model service, account or renderer download is needed.
Serve the output with a static server. Hosting, access control and uploading
are separate owner decisions. Preserve all emitted license notices.

The init-first home and Rust/Tauri support are unreleased source/local-candidate features; public
npm 0.1.0 predates it. Use a candidate containing this change, not a claim that
the existing registry version was updated.
Init-first Home and Rust/Tauri require Topocode 0.2.0 or newer. After that
release is published, install with `npm install --save-dev @jdylanmc/[email protected]`.
Release preparation is not proof of registry availability; never silently
substitute the older 0.1.0 workflow.

`topo enrich` is a separate, explicitly configured provider-command workflow for
secondary commentary. It is not required for source-grounded story editing.
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,9 @@ jobs:
- run: yarn test:regression
- name: Verify the installed public toolbelt
run: |
PACKAGE_FILE="jdylanmc-topo-code-$(node -p "require('./distribution/package.json').version").tgz"
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
node scripts/package-smoke.mjs "dist/$PACKAGE_FILE" ../renderer/dist/jdylanmc-topo-archify-0.1.0.tgz
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: npm-candidates
Expand Down
86 changes: 48 additions & 38 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,56 @@
# Changelog

Notable changes are recorded here. Initial npm candidates are version 0.1.0;
publication remains a separate release-owner action.
Notable changes to the public Topocode package are recorded here. Renderer
versions are independent; publication remains a separate release-owner action.

## Unreleased

## 0.2.0 - 2026-09-30

Release preparation date; npm publication is not implied by these notes.
Changes since the published 0.1.0 baseline. The renderer remains
`@jdylanmc/[email protected]` with pristine Archify 3.0.0.

### Added

- Create a ready-to-serve branded Home on plain or skills-enabled `topo init`,
including empty/unborn repositories. Reuse its categorized inventory across
Home and stories, retain selectable Repository exploration, and bundle
truthful unscanned sites. See #84.
- Support minimal first-party Rust language and Tauri bridge selection through
normal commands, with deterministic parser-backed evidence, lexical ownership
and explicit partial/unresolved coverage. JS/TS remains the default; no Cargo,
proc-macro or model execution is introduced.
- Add hash-bound technical Workflow stories with decision/data shapes, exact
node/edge excerpts and source-traced versus inferred connections. Explicit
Graphviz 16.0.0 has its own layout receipts and a narrowly pinned embedded
EPL-2.0 exception with full notices/source availability. See #85.
- Include generic Rust/Tauri fixtures and installed authoring/operation guidance
for fresh contexts and cache recreation, without consumer application data.

### Fixed

- Share one app-owned theme across shell, evidence, authored/generated viewers,
focus navigation and native default exports without modifying renderer bytes.
- Preserve Rust impl/trait methods through validated publication, preview and
bundle; structural owner identities keep named methods and qualified anchors
stable across comment-only moves.
- Reject uncertain Tauri helper positions across spreads/rest bindings and
invalidate obsolete helpers after dot/computed-member writes while preserving
known scalar and unmodified-receiver controls.
- Preserve renderer-owned evidence/specification assets and distinguish native
from adapted/shared-output hashes. Roll back reported replacement failures
and reject orphaned preview caches rather than publishing mixed generations.
- Keep byte-pinned upstream license files unchanged through Windows-style Git
checkout conversion without weakening digest checks.

## 0.1.0

Initial public release baseline:
[`6c7b5c9`](https://github.com/jdylanmc/topo-code/tree/6c7b5c926d54fadcae51c450edfb210cd6be38dc),
tag `npm-bootstrap/v0.1.0-6c7b5c926d54fadcae51c450edfb210cd6be38dc`.
The original preparation entries below are retained as historical notes.

### Renderer upgrade

- Upgrade `@topo/diagram-core` to the complete pristine Archify 3.0.0 release
Expand All @@ -23,26 +69,6 @@ publication remains a separate release-owner action.

### Added

- Support explicit first-party Rust language and Tauri bridge selection through
normal scan/preview/bundle commands, retaining JS/TS defaults, deterministic
source identities, lexical ownership, per-plugin partial/unresolved evidence
and conservative shadowing/mutation handling. No Cargo, proc-macro or model
execution is introduced.
- Add snapshot-bound technical Workflow stories with decision/data shapes,
exact node/edge excerpts and source-traced versus inferred connections.
Explicit Graphviz 16.0.0 rendering has engine-specific layout receipts and a
narrowly pinned embedded EPL-2.0 exception with full notices and source
availability. Native diagram families remain unchanged.
- Ship generic Rust/Tauri fixtures, installed authoring/operation guidance and
transferable parser, rendering, theme, publication and regeneration findings.
No consumer application's authored diagrams or caches are included.

- Create a ready-to-serve, branded diagram Home on plain or skills-enabled
`topo init`, including empty/unborn repositories without scanning. Reuse the
categorized inventory across Home and native story pages, keep Repository
exploration selectable and old deep links working, and bundle truthful
unscanned sites with notices. This is unreleased; public npm 0.1.0 is unchanged.

- Add GitHub-only publication of verified tarballs: normal OIDC and explicit
first-package bootstrap through version/commit-bound tags, with a UI-managed
token exposed only to its publish step. No local npm authentication is needed.
Expand Down Expand Up @@ -142,22 +168,6 @@ publication remains a separate release-owner action.

### Fixed

- Retain Rust impl/trait methods through validated Repository publication,
preview, bundle and cache recreation. Structural impl/extern owner identities
keep named descendants and qualified anchors stable across comment-only moves.
- Reject uncertain Tauri helper positions across spreads/rest bindings and
invalidate obsolete helpers after equivalent dot/computed-member writes,
while preserving known scalar and unmodified-receiver controls.
- Preserve byte-pinned upstream license files through Git checkout conversion,
including Windows autocrlf, without weakening exact license digest gates.

- Make shell, evidence, authored/generated viewers and native default exports
share one app-owned theme across focus navigation, stored preferences, media
changes and native actions without altering pristine renderer package bytes.
- Preserve renderer-owned evidence/specification assets through scan and bundle,
distinguish native and adapted/shared-output hashes, and roll back reported
generation-replacement failures rather than leaving mixed generations.

- Publish explicit local tarball paths so npm cannot interpret `dist/filename.tgz`
as GitHub shorthand; verify both release modes with offline dry-run publication.
- Prevent static-bundle browser fixture cleanup from waiting on unused TCP
Expand Down
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,34 +14,34 @@ No hosted service, no telemetry, no account.

Normal commands also support explicitly selected, parser-backed **Rust/Tauri**
and snapshot-bound technical workflows with decisions, exact node/edge source
evidence and an explicit Graphviz renderer. These capabilities are unreleased;
the existing registry 0.1.0 is unchanged. See [supported configuration, portable
evidence and an explicit Graphviz renderer in **Topocode 0.2.0**.
See [supported configuration, portable
examples and limits](./docs/rust-tauri.md).

The goal is to put a software engineer in the human-in-the-loop position: every
claim the tool makes about a codebase is backed by evidence you can follow, and
everything a human adds is recorded as such.

> **Status: Local preview.** The scan-to-site workflow, deterministic reports,
> **Release preparation: 0.2.0.** The scan-to-site workflow, deterministic reports,
> source-grounded stories, static analysis modules, optional AI commentary, and
> pinned Archify 3.0.0 rendering are implemented. Topo is the storybook for
> architects: the generated shell inventories every diagram while preserving
> real Archify viewers. npm candidate packages and portable project skills are
> available; registry publication remains a separate release-owner step.
> real Archify viewers. This source prepares the next minor release; registry
> publication remains a separate release-owner step.

## Install the toolbelt

The public `@jdylanmc/[email protected]` predates the init-first home described
here. Use a locally built candidate tarball for this unreleased behavior; no
version bump or publication is implied. After installing the candidate, run
Once 0.2.0 is published, install the public package below. Its exact
`@jdylanmc/[email protected]` dependency is installed automatically; no source
checkout or paired tarball is required. Then run
`npm exec --no -- topo init . --skills`. This adds project-local Topocode skills
and instructions without replacing existing files. Read
`.agents/skills/topo/SKILL.md`, serve, author/validate stories, preview and bundle
using the installed CLI. Plain `topo init` creates the same site without skills.
Install both candidate tarballs in one npm command:
Version 0.2.0 adds init-first Home and the supported Rust/Tauri workflow:

```sh
npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz
npm install --save-dev @jdylanmc/topo-code@0.2.0
npm exec --no -- topo init . --skills
npm exec --no -- topo serve .
```
Expand Down Expand Up @@ -141,7 +141,8 @@ node /absolute/path/to/topo-code/packages/cli/dist/main.js scan "$PWD"
```

Documentation uses `topo` as shorthand for that built entry point. The supported
input for scanning is a local Git repository containing TypeScript/JavaScript.
input for scanning is a local Git repository containing TypeScript/JavaScript,
or explicitly selected Rust/Tauri source as described in the technical guide.
Initialization and authored stories do not require scannable source. Unknown
configuration, unresolved local/workspace imports and incomplete scans fail
explicitly. An intentional `--allow-partial` preview is visibly non-authoritative
Expand Down
18 changes: 8 additions & 10 deletions distribution/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,18 @@ project agent skills, schemas, prebuilt assets and notices. No hosted service or
model invocation during scanning. The exact renderer dependency is
`@jdylanmc/[email protected]`, containing pristine upstream Archify **3.0.0**.

This source prepares **Topocode 0.2.0**. Once that version is published:

```sh
npm install --save-dev /path/to/jdylanmc-topo-archify-0.1.0.tgz /path/to/jdylanmc-topo-code-0.1.0.tgz
npm install --save-dev @jdylanmc/topo-code@0.2.0
npm exec --no -- topo init . --skills
npm exec --no -- topo serve .
npm exec --no -- topo bundle . --output ./site-output --base-path /architecture/
```

The init-first Home described here is **unreleased**. The already-public
`@jdylanmc/[email protected]` predates it; use a local candidate containing this
change. No registry update or version bump is implied.

Installing both tarballs in the same command satisfies the exact renderer
dependency normally, without a fake registry, workspace links or source checkout.
The install requires the other declared public npm dependencies.
The public install resolves the exact unchanged renderer and other declared
npm dependencies automatically, without paired tarballs or workspace links.
Preparing this source/package does not itself establish registry availability.

`--skills` is opt-in: creates `.agents/skills/topo`,
`.agents/skills/topo-story-authoring`, `.agents/skills/topo-archify-maintenance`
Expand Down Expand Up @@ -47,13 +45,13 @@ provider-command surface, not part of scanning. Generated `.topo/cache` output
is disposable; configuration and authored documents are not.

Explicit first-party Rust/Tauri selection, technical decision/data workflows
and hash-bound source evidence are supported by this unreleased candidate.
and hash-bound source evidence are part of 0.2.0.
Read `docs/rust-tauri.md` and the synthetic `examples/rust-tauri/` before
configuring analysis or authoring technical stories. Rust/Tauri are parser-backed
and partial, not Cargo/rust-analyzer semantics. Graphviz is an explicit bounded
backend with its own receipts and complete EPL-2.0/source-availability notices,
not a native-renderer fallback. App-owned themes also govern native default
exports. None of these changes updates the already-published 0.1.0.
exports. Version 0.1.0 remains immutable; 0.2.0 is a distinct minor release.

Bundles are plain static files with notices; hosting, deployment and access
control are yours. Runtime rendering does not download Archify or call a model.
Expand Down
2 changes: 1 addition & 1 deletion distribution/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@jdylanmc/topo-code",
"version": "0.1.0",
"version": "0.2.0",
"description": "Local-first repository architecture storybook: topo CLI and portable agent skills.",
"type": "module",
"license": "MIT",
Expand Down
Loading
Loading