diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 11b19dd..8d5648e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -3,10 +3,12 @@ name: Publish on: push: tags: - - 'v*' + - 'v*' # telogen (root package) + - 'react-v*' # telogen-react (packages/react) jobs: publish: + if: ${{ !startsWith(github.ref_name, 'react-v') }} runs-on: ubuntu-latest permissions: contents: read @@ -49,3 +51,34 @@ jobs: grep -q "^telogen v$PKG_VERSION$" /tmp/smoke/stdout.log grep -q "generated by telogen v$PKG_VERSION" /tmp/smoke/out/llms.txt echo "smoke: OK" + + publish-react: + if: ${{ startsWith(github.ref_name, 'react-v') }} + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # for npm provenance + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + registry-url: https://registry.npmjs.org + + - name: Tag matches package version + run: | + PKG_VERSION=$(node -p "require('./packages/react/package.json').version") + [ "react-v$PKG_VERSION" = "$GITHUB_REF_NAME" ] || { echo "tag $GITHUB_REF_NAME != package $PKG_VERSION"; exit 1; } + + - name: Publish telogen-react to npm + working-directory: packages/react + run: npm publish --provenance --access public + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + - name: Smoke test (registry fetch) + run: | + sleep 15 + npm view telogen-react version diff --git a/README.md b/README.md index d2b7263..3417e58 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ content telogen currently can't reach, and maps each one to the spot you'd mark it for extraction. The file is a diagnostic map: it shows you *where* extractable content lives -inside your components. `` (from `@telogen/react`) and the CLI-side +inside your components. `` (from `telogen-react`) and the CLI-side extraction that reads it both ship together in Phase 2 — once they do, marking these spots will let telogen pick up that content on the next run. @@ -265,7 +265,7 @@ export default async function Page() { } ``` -This is a deliberate boundary: telogen analyzes each route file on its own rather than resolving import chains, which keeps it fast and dependency-free. To see what you're missing, run `npx telogen` once and open the generated `ai-annotation-guide.md` — it maps the extractable content inside your components. `` (from `@telogen/react`) and the CLI-side support for reading it both ship together in Phase 2; until then, the guide at least tells you exactly where that content is. +This is a deliberate boundary: telogen analyzes each route file on its own rather than resolving import chains, which keeps it fast and dependency-free. To see what you're missing, run `npx telogen` once and open the generated `ai-annotation-guide.md` — it maps the extractable content inside your components. `` (from `telogen-react`) and the CLI-side support for reading it both ship together in Phase 2; until then, the guide at least tells you exactly where that content is. **Pages that only call `redirect()` produce empty output.** This is expected — there is no content to extract. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..29f9f18 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,34 @@ +# Roadmap + +What's planned after v0.1.5. Order reflects current priority; nothing here +is a commitment to a date. Ideas and votes welcome in +[Discussions](https://github.com/ggange/telogen/discussions). + +## GitHub Action for auto-regeneration + +A reusable Action: on push, run `npx telogen` and commit updated `llms.txt` +and `.md` files when they change. Keeps generated output in lockstep with +your source without a manual re-run — the answer to "won't this go stale?" + +## `` — telogen-react + +The [telogen-react](https://www.npmjs.com/package/telogen-react) package +will ship an `` React component (a Fragment passthrough — zero +DOM, zero layout impact) together with CLI-side extraction that follows +imports to read it. Marking content inside your components makes it visible +to telogen even where heuristics can't reach. The `ai-annotation-guide.md` +telogen generates today maps where annotation will be useful. + +## One-hop import extraction + +Extend extraction to follow imports one level deep — relative paths, +tsconfig/jsconfig `paths` aliases, and barrel files — so component-shell +pages (`return `) produce real content instead of an empty page. + +## Build-platform plugins + +Vercel and Netlify build plugins for zero-config generation on deploy. + +## More routers + +Remix and Astro support, as listed in the README. diff --git a/TODOS.md b/TODOS.md deleted file mode 100644 index 2512e71..0000000 --- a/TODOS.md +++ /dev/null @@ -1,76 +0,0 @@ -# TODOs - -Deferred work with context. Effort: S/M/L/XL (human team) — with AI-assisted -development typically one size smaller. Priority: P1 (next up) / P2 / P3. - -## P1 — first week post-HN - -### GitHub Action for auto-regeneration -- **What:** Reusable Action: on push, run `npx telogen`, commit updated - `llms.txt` + `.md` files with `[skip ci]` if changed; publish to the - GitHub Marketplace. -- **Why:** Kills the stale-llms.txt objection (the #1 legit criticism of - build-time generation) and opens a distribution channel. -- **Context:** Spec'd in the 2026-06-29 CEO plan (scope item 4). Deferred - from the pre-HN window (D2, 2026-07-04) to keep launch week focused on - first-run reliability. Needs `contents: write` permission; exit 0 on - zero-diff, non-zero on CLI error. -- **Effort:** S · **Depends on:** stable v0.1.5 - -### Show HN post (Monday 2026-07-07) -- **What:** Write the post: confront the Ahrefs "97% of llms.txt never - read" stat in the first paragraph (it measures crawlers; IDE/user-directed - agents do fetch it), CSR/build-time differentiation table, traction line - (400+ downloads organic), "never executes your code." -- **Why:** The post is the launch surface; the 97%-stat rebuttal is the - make-or-break comment-thread move. -- **Effort:** S (human-written by choice, D8) - -## P2 — post-launch roadmap (from 2026-06-29 plan Phase 2) - -### Vercel build plugin -- **What:** Self-install npm package first; submit Marketplace application - immediately (approval historically 4–12 weeks). -- **Why:** Zero-config for Vercel-native developers. -- **Effort:** M - -### Netlify build plugin -- **What:** Separate package, separate plugin API; ship independently. -- **Effort:** M - -### @telogen/react full implementation -- **What:** v1 component (Fragment passthrough) + CLI-side extraction via - import-binding tracking (handles aliased imports; do NOT hardcode the - string "AIContent"). Spec in 2026-06-29 CEO plan. -- **Why:** Closes the "content inside custom components" gap for annotated - code; the "aria-label for AI" bet. -- **Depends on:** user signal that the annotation guide is used; placeholder - package published (pre-HN checklist). -- **Effort:** M - -### One-hop import extraction — remainder (if cut at the Sunday gate) -- **What:** Whatever of the one-hop resolver (tsconfig `paths` aliases, - barrel files, depth-1 component extraction) didn't ship in v0.1.5; - extend to `extends` chains and wildcard patterns → v0.2.0. -- **Context:** Spec + minimum-alias bar in the 2026-07-04 CEO plan - (~/.gstack/projects/ggange-agentify/ceo-plans/). -- **Effort:** M - -### CI publish pipeline for @telogen/react -- **What:** Wire `packages/react` into the tag-triggered publish workflow - (same provenance flow `publish.yml` gives the root package; scoped tag - like `react-v*` or a workspace-aware release step). -- **Why:** The placeholder is a one-off manual `npm publish`; real - @telogen/react releases (Phase 2 AIContent) need the same repeatable, - provenance-signed path as telogen itself. -- **Context:** Flagged in the 2026-07-04 eng review distribution check — - `publish.yml` only builds/publishes the root package. -- **Depends on:** @telogen/react real implementation starting. -- **Effort:** S - -## P3 - -### Windows deep-dive -- **What:** If the pre-HN Windows CI timebox trips on secondary bugs - (beyond the posix-glob fix), finish the remaining failures here. -- **Effort:** S–M, unknown until CI runs diff --git a/examples/demo/ai-annotation-guide.md b/examples/demo/ai-annotation-guide.md index 926852f..f7e5894 100644 --- a/examples/demo/ai-annotation-guide.md +++ b/examples/demo/ai-annotation-guide.md @@ -11,7 +11,7 @@ reach — with the exact spot you'd mark each one for extraction. impact.** Once it ships, it will mark content for telogen to include in per-route `.md` files. -The `` component (from `@telogen/react`) and the CLI-side support for +The `` component (from `telogen-react`) and the CLI-side support for reading it both ship together in telogen Phase 2 — neither exists yet, so the suggestions below are a preview of where annotation will go, not something to use today. Watch [github.com/ggange/telogen](https://github.com/ggange/telogen) for the diff --git a/packages/react/README.md b/packages/react/README.md index 0c013b9..ce253fa 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,4 +1,4 @@ -# @telogen/react +# telogen-react > Companion package for [telogen](https://github.com/ggange/telogen). The `` > component ships here with telogen Phase 2 — it is not published yet. @@ -11,7 +11,7 @@ with it will let telogen pick it up on the next run. ## Planned API ```tsx -import { AIContent } from '@telogen/react'; +import { AIContent } from 'telogen-react'; // Wraps any content to make it visible to AI agents via telogen function Hero({ title }: { title: string }) { @@ -30,6 +30,6 @@ extraction. ## Timeline - `telogen` v0.1.0 — annotation guide tells you *where* to add `` -- `@telogen/react` v0.1.0 — ships the actual component (Phase 2) +- `telogen-react` v0.1.0 — ships the actual component (Phase 2) Follow progress at [github.com/ggange/telogen](https://github.com/ggange/telogen). diff --git a/packages/react/index.js b/packages/react/index.js index e26bd84..b8d482d 100644 --- a/packages/react/index.js +++ b/packages/react/index.js @@ -1,3 +1,3 @@ -// @telogen/react v0.0.1 — companion package for telogen. +// telogen-react v0.0.1 — companion package for telogen. // The AIContent component ships in v0.1.0 alongside telogen Phase 2. // See https://github.com/ggange/telogen for timeline. diff --git a/packages/react/package.json b/packages/react/package.json index c62729c..b3a9d74 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -1,5 +1,5 @@ { - "name": "@telogen/react", + "name": "telogen-react", "version": "0.0.1", "description": "AIContent component for telogen — companion package. The component ships with telogen Phase 2.", "type": "module", diff --git a/src/annotation-guide.ts b/src/annotation-guide.ts index 438f9a6..005d00d 100644 --- a/src/annotation-guide.ts +++ b/src/annotation-guide.ts @@ -155,7 +155,7 @@ export function renderAnnotationGuide(files: FileAnnotations[]): string { 'impact.** Once it ships, it will mark content for telogen to include in per-route', '`.md` files.', '', - 'The `` component (from `@telogen/react`) and the CLI-side support for', + 'The `` component (from `telogen-react`) and the CLI-side support for', 'reading it both ship together in telogen Phase 2 — neither exists yet, so the', 'suggestions below are a preview of where annotation will go, not something to use', 'today. Watch [github.com/ggange/telogen](https://github.com/ggange/telogen) for the',