@purview-dev/pm-docs-site 0.0.0-stage → 0.1.0-pre.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE.md +9 -0
  2. package/README.md +219 -2
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +90 -0
  5. package/dist/index.d.ts +7 -0
  6. package/dist/index.js +118 -0
  7. package/dist/options.d.ts +5 -0
  8. package/dist/options.js +46 -0
  9. package/dist/repo-docs.d.ts +33 -0
  10. package/dist/repo-docs.js +94 -0
  11. package/dist/schema-version.d.ts +10 -0
  12. package/dist/schema-version.js +19 -0
  13. package/dist/sidebar.d.ts +10 -0
  14. package/dist/sidebar.js +30 -0
  15. package/dist/site-options.d.ts +9 -0
  16. package/dist/site-options.js +39 -0
  17. package/dist/types.d.ts +47 -0
  18. package/dist/types.js +4 -0
  19. package/lib/repo-docs.ts +124 -0
  20. package/lib/schema-version.ts +24 -0
  21. package/package.json +68 -5
  22. package/src/components/ExportStamp.astro +29 -0
  23. package/src/components/FeatureSummary.astro +160 -0
  24. package/src/components/FeatureTable.astro +64 -0
  25. package/src/components/ItemDetail.astro +16 -0
  26. package/src/components/ItemDialog.astro +16 -0
  27. package/src/components/LinkedFrom.astro +33 -0
  28. package/src/components/LinkedText.astro +12 -0
  29. package/src/components/PlanInteractions.astro +30 -0
  30. package/src/components/RefLink.astro +18 -0
  31. package/src/components/StateBadge.astro +15 -0
  32. package/src/components/board/Board.tsx +244 -0
  33. package/src/components/board/KanbanItemCard.tsx +129 -0
  34. package/src/components/board/LinkRuns.tsx +21 -0
  35. package/src/components/board/TaskKanbanCard.tsx +81 -0
  36. package/src/components/board/useBoardUrlState.ts +41 -0
  37. package/src/components/lib/KanbanItemCard.astro +264 -0
  38. package/src/components/lib/StatusTimelineFeed.astro +194 -0
  39. package/src/components/lib/TaskKanbanCard.astro +215 -0
  40. package/src/components/timeline/Timeline.tsx +159 -0
  41. package/src/components/timeline/useTimelineLayout.ts +39 -0
  42. package/src/content.config.ts +16 -0
  43. package/src/env.d.ts +7 -0
  44. package/src/lib/board-data.ts +84 -0
  45. package/src/lib/board.ts +209 -0
  46. package/src/lib/planning-types.ts +207 -0
  47. package/src/lib/planning.ts +415 -0
  48. package/src/lib/references.ts +360 -0
  49. package/src/lib/timeline.ts +156 -0
  50. package/src/loaders/repo-docs.ts +69 -0
  51. package/src/pages/index.astro +158 -0
  52. package/src/pages/plan/board.astro +41 -0
  53. package/src/pages/plan/log.astro +83 -0
  54. package/src/pages/plan/risks/[id].astro +72 -0
  55. package/src/pages/plan/risks.astro +263 -0
  56. package/src/pages/plan/roadmap.astro +108 -0
  57. package/src/routes/plan/briefs.astro +66 -0
  58. package/src/routes/plan/features/[id].astro +113 -0
  59. package/src/routes/plan/features/index.astro +29 -0
  60. package/src/routes/plan/inbox.astro +78 -0
  61. package/src/routes/plan/milestones/[milestone].astro +113 -0
  62. package/src/routes/plan/milestones/index.astro +56 -0
  63. package/src/routes/plan/now.astro +135 -0
  64. package/src/routes/plan/strategy.astro +194 -0
  65. package/src/scripts/plan.ts +40 -0
  66. package/src/styles/components.css +491 -0
  67. package/src/styles/kanban.css +277 -0
  68. package/src/styles/timeline.css +210 -0
  69. package/src/styles/width.css +4 -0
package/LICENSE.md ADDED
@@ -0,0 +1,9 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright © 2026 Kieron Lanning
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,220 @@
1
- # Temporary Holding Version
1
+ # @purview-dev/pm-docs-site
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A local, searchable project site for [pm-skills](https://github.com/purview-dev/pm-skills):
4
+ the plan from `planning.json` (written by the `pm-export` skill) and,
5
+ optionally, the repository's Markdown, rendered by Astro and Starlight.
6
+
7
+ **Documentation:** [PM Skills documentation](https://purview.dev/docs/pm-skills/)
8
+ on purview.dev (the *Docs-site package* guide page), part of the
9
+ [PM Skills](https://purview.dev/projects/pm-skills/) project.
10
+
11
+ Prerelease: builds are on npm under the `prerelease` dist-tag
12
+ (`bun add @purview-dev/pm-docs-site@prerelease`). Until roadmap item R-013
13
+ migrates the `pm-docs-site` skill to it, the skill and this repository's
14
+ `docs-site/` still render the skill's templates.
15
+
16
+ ## A consumer site
17
+
18
+ Three files: `package.json`, a lockfile, and `astro.config.ts`. No `src/`
19
+ folder: the integration points Astro's `srcDir` at the package.
20
+
21
+ ```json
22
+ {
23
+ "name": "my-project-site",
24
+ "private": true,
25
+ "type": "module",
26
+ "scripts": {
27
+ "dev": "pm-docs-site dev",
28
+ "build": "pm-docs-site build",
29
+ "check": "pm-docs-site check"
30
+ },
31
+ "dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.1" }
32
+ }
33
+ ```
34
+
35
+ ```js
36
+ // astro.config.ts
37
+ import pmDocsSite from '@purview-dev/pm-docs-site';
38
+
39
+ export default {
40
+ integrations: [
41
+ pmDocsSite({
42
+ title: 'My project',
43
+ planning: '../planning/planning.json',
44
+ docs: {
45
+ root: '..',
46
+ sources: [{ label: 'Project', base: '.', include: ['README.md'], prefix: 'project/' }],
47
+ },
48
+ }),
49
+ ],
50
+ };
51
+ ```
52
+
53
+ ## Options
54
+
55
+ | Option | Type | Default |
56
+ | --- | --- | --- |
57
+ | `title` | string | required |
58
+ | `description` | string | none |
59
+ | `planning` | path from the site root | `../planning/planning.json` |
60
+ | `docs` | `{ root, sources }`; `root` from the site root, each source a folder and globs | none: no repository pages |
61
+ | `views` | any of `now`, `milestones`, `features`, `inbox`, `briefs`, `strategy` | all six |
62
+
63
+ Home, Board, Roadmap, Log and Risks are always rendered. A docs source has
64
+ `label`, `base`, `include`, and optionally `prefix`, `indexFile`, `order`,
65
+ `collapsed`, and `hidden` (see `lib/types.ts`).
66
+
67
+ ## Board
68
+
69
+ The Board is a React island, hydrated on load: every roadmap item in five
70
+ columns (Now, Next, For you, Waiting, Done), filtered and grouped without a
71
+ page reload.
72
+
73
+ | Filter | Values |
74
+ | --- | --- |
75
+ | Owner | `agent`, `user`, `both` |
76
+ | Milestone | each milestone in the plan, or `none` (no milestone) |
77
+ | Size | `S`, `M`, `L` |
78
+ | RAG | `red`, `amber`, `green`, or `none` (no risk) |
79
+
80
+ Filters combine with AND. A card's RAG is the worst of the open, mitigating,
81
+ or accepted risks that affect it (closed risks and milestone-level risks
82
+ never colour a card). Group by `none` (today's board), `milestone`, or
83
+ `owner`, which splits the board into one lane per group, each holding all
84
+ five columns.
85
+
86
+ Filter and group state lives in the URL query string, in that order
87
+ (`owner`, `milestone`, `size`, `rag`, `group`), so a filtered or grouped
88
+ board can be linked and survives a reload:
89
+ `/plan/board/?owner=user&milestone=M2&group=milestone`. Unknown or junk
90
+ values fall back to All / None. Column collapse still works per column,
91
+ across every lane, and without JavaScript the full, ungrouped board renders
92
+ with the filter bar hidden.
93
+
94
+ The integration adds `@astrojs/react` itself, so a consumer site stays the
95
+ three files above.
96
+
97
+ ## Roadmap timeline
98
+
99
+ The Roadmap page opens with a timeline: a React island with one card per
100
+ milestone, in strategy order, then a `No milestone` card when it has items
101
+ that are not dropped. Each card shows the milestone ID and name (a link to
102
+ its milestone page when the Milestones view is on), a `Focus` badge, its
103
+ status (with the done date), its target or `No target`, and
104
+ `<done> of <total> done` with a progress bar.
105
+
106
+ The strip runs left to right by default and scrolls sideways inside itself;
107
+ a plain vertical wheel scrolls it sideways until it reaches an end, then
108
+ the page scrolls. `Top to bottom` lays it out vertically, and the choice is
109
+ kept in the URL as `?layout=vertical`, alongside any other parameters, so a
110
+ link opens the same layout.
111
+
112
+ Zoom runs from 50% to 200% in steps of 25%: the `Zoom out`, `Zoom in`, and
113
+ `Reset zoom` buttons, Ctrl or Cmd + wheel over the strip, or a trackpad
114
+ pinch. Zoom resizes the cards rather than scaling the page, and it is not
115
+ kept in the URL: every visit starts at 100%.
116
+
117
+ ## CLI
118
+
119
+ The CLI runs under Node 24 or later.
120
+
121
+ - `pm-docs-site build [site-dir]` and `pm-docs-site dev [site-dir]` run Astro
122
+ on the site. A site with no `astro.config.*` builds from
123
+ `--title <title>` and `--planning <path>`.
124
+ - `pm-docs-site check [site-dir]` builds nothing. It reads the export, checks
125
+ its `schemaVersion`, and checks every docs source folder exists, then exits
126
+ 0, or 1 with one line per problem.
127
+
128
+ ## Supported exports
129
+
130
+ `SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.ts`: pm-export
131
+ `schemaVersion` 3. Any other version fails the build and `check`, and the
132
+ message says to run the `pm-export` skill.
133
+
134
+ ## Development
135
+
136
+ ```bash
137
+ just package-test # bun install --frozen-lockfile, bun test, bun run check
138
+ ```
139
+
140
+ `bun test` includes a build of the fixture site whose page list must equal
141
+ `test/fixtures/expected-pages.txt`, and a build from the packed tarball
142
+ installed into a temporary folder.
143
+
144
+ ## Releasing
145
+
146
+ The package is versioned on its own, by `version` in this `package.json`,
147
+ not by the repository's skills version, and tagged `pm-docs-site-v<version>`.
148
+ The release follows purview-dev/astroc4: bump `version` and merge to `main`.
149
+ That is the whole process.
150
+
151
+ ### Version changes
152
+
153
+ `scripts/check-version.ts` runs on every pull request (and the pre-push
154
+ hook) and fails when the package's version:
155
+
156
+ - is not SemVer (`MAJOR.MINOR.PATCH`, optionally `-<prerelease>`),
157
+ - is older than the version on `main`,
158
+ - was bumped to a version whose `pm-docs-site-v<version>` tag exists, or
159
+ - is a prerelease of an already released version.
160
+
161
+ A bump is not required: a change that keeps the version merges, and the
162
+ publish workflow then skips it (REL002).
163
+
164
+ ### The publish workflow
165
+
166
+ A change to this `package.json` on `main` runs
167
+ `.github/workflows/publish-pm-docs-site.yml`. Its eligibility step applies
168
+ the purview-dev release rules:
169
+
170
+ | Rule | Passes when | Otherwise |
171
+ | --- | --- | --- |
172
+ | REL001 | the version is SemVer | fails |
173
+ | REL002 | `pm-docs-site-v<version>` is not tagged | skips, green: the version is released |
174
+ | REL003 | a stable version runs from `main` | fails |
175
+
176
+ While `package.json` sets `"private": true` it also skips, green. Then it
177
+ installs, tests, type-checks, builds `dist/`, and runs `scripts/check-exports.ts`.
178
+ The `prepack` script runs the same build and check, so every pack and a local
179
+ `npm publish` build first and cannot burn a version on a package with missing
180
+ or non-JavaScript entry points. It publishes a prerelease
181
+ (`0.1.0-pre.1`) under the `prerelease` dist-tag and a stable version under
182
+ `latest`, skips a version already on the registry, and keeps `latest` on the
183
+ newest prerelease until a stable release exists. Only then does it create the
184
+ tag and a GitHub release, never marked as the repository's latest release.
185
+ Every step is idempotent, so re-run it from the Actions tab
186
+ (`workflow_dispatch`).
187
+
188
+ The tag is written only by the workflow. A hand-pushed
189
+ `pm-docs-site-v<version>` tag makes the release of that version skip.
190
+
191
+ ### Authentication: npm trusted publishing
192
+
193
+ The workflow holds no npm token: `id-token: write` lets npm exchange the
194
+ job's OIDC token for a short-lived publish credential, and npm attaches
195
+ provenance itself. `scripts/workflows.test.ts` fails a pull request that adds
196
+ a token, `registry-url`, or `--provenance`. The job runs in the GitHub `npm`
197
+ environment.
198
+
199
+ A trusted publisher is configured on the package, so the package must exist
200
+ on npm first. Once, from an account that can publish to `@purview-dev`:
201
+
202
+ 1. Remove `"private": true`, set the first version (`0.1.0-pre.1`), and
203
+ publish it locally: `npm publish --access public --tag prerelease`.
204
+ 2. Add the trusted publisher, with *Allow npm publish* and *Allow npm
205
+ dist-tag* ticked (the CLI grants only the first):
206
+
207
+ ```sh
208
+ npm trust github @purview-dev/pm-docs-site \
209
+ --repo purview-dev/pm-skills \
210
+ --file publish-pm-docs-site.yml \
211
+ --allow-publish
212
+ npm trust list @purview-dev/pm-docs-site
213
+ ```
214
+
215
+ 3. Merge that version bump. Its tag does not exist yet, so the workflow
216
+ finds the version on the registry, skips the publish, and writes the tag
217
+ and the release. Every later version is published by the workflow.
218
+
219
+ Renaming `publish-pm-docs-site.yml` stops publishing until the trusted
220
+ publisher is re-created, because npm validates the workflow filename.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,90 @@
1
+ #!/usr/bin/env node
2
+ // pm-docs-site <dev | build | check> [site-dir] [--title <t>] [--planning <p>]
3
+ //
4
+ // dev and build run Astro on the site folder: with its astro.config file when it
5
+ // has one, else with the integration built from --title and --planning. check
6
+ // builds nothing: it reads the export and the docs sources and reports problems.
7
+ import { existsSync, readFileSync } from 'node:fs';
8
+ import { resolve } from 'node:path';
9
+ import { resolveOptions } from "./options.js";
10
+ import { checkSchemaVersion } from "./schema-version.js";
11
+ import { loadSiteOptions } from "./site-options.js";
12
+ const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
13
+ function parse(argv) {
14
+ const flags = {};
15
+ const positional = [];
16
+ for (let index = 0; index < argv.length; index++) {
17
+ const arg = argv[index];
18
+ if (arg === '--title' || arg === '--planning') {
19
+ const value = argv[++index];
20
+ if (value === undefined)
21
+ throw new Error(`pm-docs-site: ${arg} needs a value`);
22
+ flags[arg === '--title' ? 'title' : 'planning'] = value;
23
+ }
24
+ else {
25
+ positional.push(arg);
26
+ }
27
+ }
28
+ return { command: positional[0], siteDir: resolve(positional[1] ?? process.cwd()), flags };
29
+ }
30
+ /** The problems check finds, one line each. */
31
+ function problems(options) {
32
+ const found = [];
33
+ if (!existsSync(options.planning)) {
34
+ found.push(`No plan export at ${options.planning}. Run the pm-export skill to write planning.json.`);
35
+ }
36
+ else {
37
+ try {
38
+ const planning = JSON.parse(readFileSync(options.planning, 'utf8'));
39
+ checkSchemaVersion(planning.schemaVersion, options.planning);
40
+ }
41
+ catch (error) {
42
+ found.push(error.message);
43
+ }
44
+ }
45
+ for (const source of options.docs?.sources ?? []) {
46
+ const base = resolve(options.docs?.root ?? '.', source.base);
47
+ if (!existsSync(base))
48
+ found.push(`docs source "${source.label}": no folder at ${base}`);
49
+ }
50
+ return found;
51
+ }
52
+ async function main() {
53
+ const { command, siteDir, flags } = parse(process.argv.slice(2));
54
+ if (command !== 'dev' && command !== 'build' && command !== 'check') {
55
+ console.error(USAGE);
56
+ return 2;
57
+ }
58
+ const { options, configFile } = await loadSiteOptions(siteDir, flags);
59
+ if (command === 'check') {
60
+ const resolved = resolveOptions(options, siteDir);
61
+ const found = problems(resolved);
62
+ for (const line of found)
63
+ console.error(`pm-docs-site: ${line}`);
64
+ if (found.length)
65
+ return 1;
66
+ const { schemaVersion } = JSON.parse(readFileSync(resolved.planning, 'utf8'));
67
+ console.log(`pm-docs-site: ok (${resolved.planning}, schemaVersion ${schemaVersion})`);
68
+ return 0;
69
+ }
70
+ const astro = await import('astro');
71
+ const inline = { root: siteDir };
72
+ if (!configFile) {
73
+ const { default: pmDocsSite } = await import("./index.js");
74
+ Object.assign(inline, { configFile: false, integrations: [pmDocsSite(options)] });
75
+ }
76
+ if (command === 'build') {
77
+ await astro.build(inline);
78
+ return 0;
79
+ }
80
+ await astro.dev(inline);
81
+ // The dev server keeps the process alive until it is stopped.
82
+ return null;
83
+ }
84
+ main().then((code) => {
85
+ if (code !== null)
86
+ process.exitCode = code;
87
+ }, (error) => {
88
+ console.error(error instanceof Error ? error.message : error);
89
+ process.exitCode = 1;
90
+ });
@@ -0,0 +1,7 @@
1
+ import type { AstroIntegration } from 'astro';
2
+ import type { PmDocsSiteOptions } from './types.js';
3
+ export type * from './types.js';
4
+ /** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
5
+ export default function pmDocsSite(options: PmDocsSiteOptions): AstroIntegration & {
6
+ pmDocsSiteOptions: PmDocsSiteOptions;
7
+ };
package/dist/index.js ADDED
@@ -0,0 +1,118 @@
1
+ // The pm-docs-site Astro integration. The consumer's astro.config.ts holds
2
+ // only `integrations: [pmDocsSite({ title, ... })]`: this points Astro's srcDir
3
+ // at the package's own src/ (pages, components, content config), adds
4
+ // Starlight with the plan sidebar, adds React so pages can render `.tsx` islands with
5
+ // no consumer config, and serves the resolved options to the pages as
6
+ // `virtual:pm-docs-site/config`.
7
+ import { existsSync } from 'node:fs';
8
+ import { dirname, join, resolve } from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+ import react from '@astrojs/react';
11
+ import starlight from '@astrojs/starlight';
12
+ import { resolveOptions } from "./options.js";
13
+ import { buildSidebar } from "./sidebar.js";
14
+ /**
15
+ * The pages each optional view owns, in src/routes/ so Astro routes them only
16
+ * when the view is on. Home, Board, Roadmap, Log and Risks are in src/pages/.
17
+ */
18
+ const VIEW_ROUTES = {
19
+ now: [['/plan/now', 'plan/now.astro']],
20
+ milestones: [
21
+ ['/plan/milestones', 'plan/milestones/index.astro'],
22
+ ['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
23
+ ],
24
+ features: [
25
+ ['/plan/features', 'plan/features/index.astro'],
26
+ ['/plan/features/[id]', 'plan/features/[id].astro'],
27
+ ],
28
+ inbox: [['/plan/inbox', 'plan/inbox.astro']],
29
+ briefs: [['/plan/briefs', 'plan/briefs.astro']],
30
+ strategy: [['/plan/strategy', 'plan/strategy.astro']],
31
+ };
32
+ const PACKAGE_NAME = '@purview-dev/pm-docs-site';
33
+ const REACT_INTEGRATION = '@astrojs/react';
34
+ const NO_EXTERNAL = ['@astrojs/starlight', PACKAGE_NAME];
35
+ const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
36
+ /**
37
+ * Whether `name` is installed in a node_modules folder at or above `root`,
38
+ * walked as Vite resolves it: under Bun, `createRequire` also finds Bun's
39
+ * global cache, which Vite never looks in.
40
+ */
41
+ function resolvesFrom(name, root) {
42
+ for (let dir = resolve(root);; dir = dirname(dir)) {
43
+ if (existsSync(join(dir, 'node_modules', name, 'package.json')))
44
+ return true;
45
+ if (dirname(dir) === dir)
46
+ return false;
47
+ }
48
+ }
49
+ /**
50
+ * The `optimizeDeps.include` entries the site lacks. The island's renderer
51
+ * (@astrojs/react-renderer) imports react-dom/client from under node_modules,
52
+ * which Vite's dev optimizer skips, so React's CommonJS reaches the browser
53
+ * raw and the Board never hydrates. An installed package is pre-bundled
54
+ * through itself (`<package> > react-dom/client`); a site that cannot resolve
55
+ * the package by name (this repository's fixtures) names react-dom/client
56
+ * plainly, since naming a package Vite cannot resolve breaks the optimizer.
57
+ * Only missing entries: Vite's mergeConfig concatenates arrays.
58
+ */
59
+ function optimizedDependencies(include, root) {
60
+ const existing = Array.isArray(include) ? include : [];
61
+ const entry = resolvesFrom(PACKAGE_NAME, root) ? `${PACKAGE_NAME} > react-dom/client` : 'react-dom/client';
62
+ return existing.includes(entry) ? [] : [entry];
63
+ }
64
+ const VIRTUAL_ID = 'virtual:pm-docs-site/config';
65
+ const RESOLVED_ID = `\0${VIRTUAL_ID}`;
66
+ /** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
67
+ export default function pmDocsSite(options) {
68
+ return {
69
+ name: 'pm-docs-site',
70
+ pmDocsSiteOptions: options,
71
+ hooks: {
72
+ 'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
73
+ const root = fileURLToPath(config.root);
74
+ const resolved = resolveOptions(options, root);
75
+ // A consumer that adds React itself keeps its own: two would register the renderer twice.
76
+ const hasReact = (config.integrations ?? []).some((integration) => integration.name === REACT_INTEGRATION);
77
+ for (const [view, routes] of Object.entries(VIEW_ROUTES)) {
78
+ if (!resolved.views[view])
79
+ continue;
80
+ for (const [pattern, file] of routes) {
81
+ injectRoute({ pattern, entrypoint: new URL(`../src/routes/${file}`, import.meta.url) });
82
+ }
83
+ }
84
+ updateConfig({
85
+ srcDir: new URL('../src/', import.meta.url),
86
+ integrations: [
87
+ starlight({
88
+ title: resolved.title,
89
+ ...(resolved.description ? { description: resolved.description } : {}),
90
+ sidebar: buildSidebar(resolved),
91
+ // Every page uses the full width (src/styles/width.css).
92
+ customCss: [fileURLToPath(new URL('../src/styles/width.css', import.meta.url))],
93
+ }),
94
+ ...(hasReact ? [] : [react()]),
95
+ ],
96
+ vite: {
97
+ optimizeDeps: { include: optimizedDependencies(config.vite?.optimizeDeps?.include, root) },
98
+ plugins: [
99
+ {
100
+ name: 'pm-docs-site:config',
101
+ resolveId: (id) => (id === VIRTUAL_ID ? RESOLVED_ID : undefined),
102
+ load: (id) => (id === RESOLVED_ID ? `export default ${JSON.stringify(resolved)};` : undefined),
103
+ },
104
+ {
105
+ // Bundle Starlight and this package in every server environment, whatever
106
+ // the consumer's package.json lists: externalised, Starlight cannot import
107
+ // astro:middleware. Astro 7 renders static pages in its own `prerender`
108
+ // environment, which top-level `vite.ssr` does not reach.
109
+ name: 'pm-docs-site:no-external',
110
+ configEnvironment: (name) => SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
111
+ },
112
+ ],
113
+ },
114
+ });
115
+ },
116
+ },
117
+ };
118
+ }
@@ -0,0 +1,5 @@
1
+ import type { PmDocsSiteOptions, ResolvedOptions, ViewName } from './types.js';
2
+ /** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
3
+ export declare const VIEW_NAMES: readonly ViewName[];
4
+ /** @param root the site root, absolute */
5
+ export declare function resolveOptions(options: PmDocsSiteOptions, root: string): ResolvedOptions;
@@ -0,0 +1,46 @@
1
+ // The integration's options: defaults, validation, and paths made absolute from
2
+ // the site root, so the pages and the content config never resolve a path again.
3
+ import { resolve } from 'node:path';
4
+ /** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
5
+ export const VIEW_NAMES = ['now', 'milestones', 'features', 'inbox', 'briefs', 'strategy'];
6
+ /** Where the export lives by default, relative to the site root. */
7
+ const DEFAULT_PLANNING = '../planning/planning.json';
8
+ /**
9
+ * Throw a pm-docs-site message for a malformed `docs` option, which a plain
10
+ * JavaScript astro.config does not type-check.
11
+ */
12
+ function checkDocs(docs) {
13
+ const value = (docs ?? {});
14
+ if (typeof value.root !== 'string')
15
+ throw new Error('pm-docs-site: docs.root must be a path');
16
+ if (!Array.isArray(value.sources))
17
+ throw new Error('pm-docs-site: docs.sources must be a list of sources');
18
+ for (const source of value.sources) {
19
+ if (typeof source?.base !== 'string' || !Array.isArray(source?.include)) {
20
+ throw new Error(`pm-docs-site: docs source "${String(source?.label)}" needs base and include`);
21
+ }
22
+ }
23
+ }
24
+ /** @param root the site root, absolute */
25
+ export function resolveOptions(options, root) {
26
+ if (!options || typeof options.title !== 'string' || options.title === '') {
27
+ throw new Error('pm-docs-site: title is required');
28
+ }
29
+ const listed = options.views ?? VIEW_NAMES;
30
+ for (const name of listed) {
31
+ if (!VIEW_NAMES.includes(name)) {
32
+ throw new Error(`pm-docs-site: unknown view "${name}"; expected one of ${VIEW_NAMES.join(', ')}`);
33
+ }
34
+ }
35
+ if (options.docs !== undefined)
36
+ checkDocs(options.docs);
37
+ const views = Object.fromEntries(VIEW_NAMES.map((name) => [name, listed.includes(name)]));
38
+ return {
39
+ title: options.title,
40
+ description: options.description ?? null,
41
+ planning: resolve(root, options.planning ?? DEFAULT_PLANNING),
42
+ planningLabel: (options.planning ?? DEFAULT_PLANNING).replace(/\\/g, '/'),
43
+ docs: options.docs ? { root: resolve(root, options.docs.root), sources: options.docs.sources } : null,
44
+ views,
45
+ };
46
+ }
@@ -0,0 +1,33 @@
1
+ import type { DocsSource } from './types.js';
2
+ export interface DocsPage {
3
+ id: string;
4
+ file: string;
5
+ }
6
+ /** A glob as a regular expression over `/`-separated paths. */
7
+ export declare function globToRegExp(glob: string): RegExp;
8
+ /** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
9
+ export declare function pageId(source: DocsSource, path: string): string;
10
+ /** Every file a source matches, as page IDs in its sidebar order. */
11
+ export declare function pagesOf(source: DocsSource, repoRoot: string): DocsPage[];
12
+ /** Simple `key: value` frontmatter (one line per key) and the body after it. */
13
+ export declare function splitFrontmatter(markdown: string): {
14
+ data: Record<string, string>;
15
+ body: string;
16
+ };
17
+ /**
18
+ * The page title and the body without it.
19
+ *
20
+ * The title is the first `# ` heading when nothing but blank lines and HTML
21
+ * comments come before it; otherwise the fallback is the title and the body is
22
+ * kept whole.
23
+ */
24
+ export declare function splitTitle(markdown: string, fallback: string): {
25
+ title: string;
26
+ body: string;
27
+ };
28
+ /** Title, description, and body for one page. */
29
+ export declare function readPage(markdown: string, file: string): {
30
+ title: string;
31
+ description?: string;
32
+ body: string;
33
+ };
@@ -0,0 +1,94 @@
1
+ // Repository Markdown as pages: which files a docs source matches, their page
2
+ // IDs, and each page's title and body. Node-loadable (no Astro or Vite import)
3
+ // because the sidebar is built from it while astro.config loads; the Astro
4
+ // loader in src/loaders/repo-docs.ts uses the same functions.
5
+ //
6
+ // Starlight requires a `title` in every page's frontmatter; repository Markdown
7
+ // rarely has one. The title is frontmatter `title`, else the first `# Title`
8
+ // heading (dropped from the body, so it is not shown twice), else frontmatter
9
+ // `name`, else the file name, so the files stay exactly as their authors write them.
10
+ import { existsSync, readdirSync } from 'node:fs';
11
+ import { basename, dirname, join, resolve, sep } from 'node:path';
12
+ /** A glob as a regular expression over `/`-separated paths. */
13
+ export function globToRegExp(glob) {
14
+ const pattern = glob
15
+ .split(/(\*\*\/|\*\*|\*)/)
16
+ .map((part) => part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
17
+ .join('');
18
+ return new RegExp(`^${pattern}$`, 'i');
19
+ }
20
+ /** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
21
+ export function pageId(source, path) {
22
+ let page = path.replace(/\.md$/i, '');
23
+ if (source.indexFile && basename(path).toLowerCase() === source.indexFile.toLowerCase()) {
24
+ page = dirname(path) === '.' ? 'index' : dirname(path);
25
+ }
26
+ return `${source.prefix ?? ''}${page}`.toLowerCase();
27
+ }
28
+ /** Every file a source matches, as page IDs in its sidebar order. */
29
+ export function pagesOf(source, repoRoot) {
30
+ const base = resolve(repoRoot, source.base);
31
+ if (!existsSync(base))
32
+ return [];
33
+ const patterns = source.include.map(globToRegExp);
34
+ const pages = readdirSync(base, { recursive: true })
35
+ .map((file) => file.split(sep).join('/'))
36
+ .filter((file) => !file.split('/').includes('node_modules') && patterns.some((pattern) => pattern.test(file)))
37
+ .map((file) => ({ id: pageId(source, file), file: join(base, file) }))
38
+ .sort((a, b) => a.id.localeCompare(b.id));
39
+ return source.order === 'desc' ? pages.reverse() : pages;
40
+ }
41
+ /** Simple `key: value` frontmatter (one line per key) and the body after it. */
42
+ export function splitFrontmatter(markdown) {
43
+ const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
44
+ if (!match)
45
+ return { data: {}, body: markdown };
46
+ const data = {};
47
+ for (const line of (match[1] ?? '').split('\n')) {
48
+ const pair = /^([\w-]+):\s*(.*?)\s*$/.exec(line);
49
+ if (pair && pair[1] && pair[2])
50
+ data[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
51
+ }
52
+ return { data, body: markdown.slice(match[0].length) };
53
+ }
54
+ /**
55
+ * The page title and the body without it.
56
+ *
57
+ * The title is the first `# ` heading when nothing but blank lines and HTML
58
+ * comments come before it; otherwise the fallback is the title and the body is
59
+ * kept whole.
60
+ */
61
+ export function splitTitle(markdown, fallback) {
62
+ const lines = markdown.split('\n');
63
+ let index = 0;
64
+ let inComment = false;
65
+ for (; index < lines.length; index++) {
66
+ const line = (lines[index] ?? '').trim();
67
+ if (inComment) {
68
+ if (line.includes('-->'))
69
+ inComment = false;
70
+ continue;
71
+ }
72
+ if (line === '')
73
+ continue;
74
+ if (line.startsWith('<!--')) {
75
+ inComment = !line.includes('-->');
76
+ continue;
77
+ }
78
+ break;
79
+ }
80
+ const heading = /^#\s+(.+?)\s*#*\s*$/.exec(lines[index] ?? '');
81
+ if (!heading || !heading[1])
82
+ return { title: fallback, body: markdown };
83
+ let start = index + 1;
84
+ while (start < lines.length && (lines[start] ?? '').trim() === '')
85
+ start++;
86
+ return { title: heading[1], body: lines.slice(start).join('\n') };
87
+ }
88
+ /** Title, description, and body for one page. */
89
+ export function readPage(markdown, file) {
90
+ const { data, body } = splitFrontmatter(markdown);
91
+ const fallback = data.name ?? basename(file, '.md');
92
+ const split = data.title ? { title: data.title, body } : splitTitle(body, fallback);
93
+ return { title: split.title, ...(data.description ? { description: data.description } : {}), body: split.body };
94
+ }
@@ -0,0 +1,10 @@
1
+ export declare const SUPPORTED_SCHEMA_VERSIONS: readonly number[];
2
+ /** The plan export is missing, unreadable, or in a format this package does not read. */
3
+ export declare class PlanningExportError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ /**
7
+ * Throw unless the export's schemaVersion is one this package reads.
8
+ * @param path the export's path, for the message
9
+ */
10
+ export declare function checkSchemaVersion(version: unknown, path: string): void;
@@ -0,0 +1,19 @@
1
+ // The pm-export schemaVersions this package reads, declared once. A new export
2
+ // format is supported by adding its version here, with the page changes it needs.
3
+ export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([3]);
4
+ /** The plan export is missing, unreadable, or in a format this package does not read. */
5
+ export class PlanningExportError extends Error {
6
+ constructor(message) {
7
+ super(`${message} Run the pm-export skill to write planning.json.`);
8
+ this.name = 'PlanningExportError';
9
+ }
10
+ }
11
+ /**
12
+ * Throw unless the export's schemaVersion is one this package reads.
13
+ * @param path the export's path, for the message
14
+ */
15
+ export function checkSchemaVersion(version, path) {
16
+ if (typeof version === 'number' && SUPPORTED_SCHEMA_VERSIONS.includes(version))
17
+ return;
18
+ throw new PlanningExportError(`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`);
19
+ }