@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.
- package/LICENSE.md +9 -0
- package/README.md +219 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +90 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +118 -0
- package/dist/options.d.ts +5 -0
- package/dist/options.js +46 -0
- package/dist/repo-docs.d.ts +33 -0
- package/dist/repo-docs.js +94 -0
- package/dist/schema-version.d.ts +10 -0
- package/dist/schema-version.js +19 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +30 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +39 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/repo-docs.ts +124 -0
- package/lib/schema-version.ts +24 -0
- package/package.json +68 -5
- package/src/components/ExportStamp.astro +29 -0
- package/src/components/FeatureSummary.astro +160 -0
- package/src/components/FeatureTable.astro +64 -0
- package/src/components/ItemDetail.astro +16 -0
- package/src/components/ItemDialog.astro +16 -0
- package/src/components/LinkedFrom.astro +33 -0
- package/src/components/LinkedText.astro +12 -0
- package/src/components/PlanInteractions.astro +30 -0
- package/src/components/RefLink.astro +18 -0
- package/src/components/StateBadge.astro +15 -0
- package/src/components/board/Board.tsx +244 -0
- package/src/components/board/KanbanItemCard.tsx +129 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +81 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- package/src/components/lib/KanbanItemCard.astro +264 -0
- package/src/components/lib/StatusTimelineFeed.astro +194 -0
- package/src/components/lib/TaskKanbanCard.astro +215 -0
- package/src/components/timeline/Timeline.tsx +159 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +16 -0
- package/src/env.d.ts +7 -0
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- package/src/lib/planning-types.ts +207 -0
- package/src/lib/planning.ts +415 -0
- package/src/lib/references.ts +360 -0
- package/src/lib/timeline.ts +156 -0
- package/src/loaders/repo-docs.ts +69 -0
- package/src/pages/index.astro +158 -0
- package/src/pages/plan/board.astro +41 -0
- package/src/pages/plan/log.astro +83 -0
- package/src/pages/plan/risks/[id].astro +72 -0
- package/src/pages/plan/risks.astro +263 -0
- package/src/pages/plan/roadmap.astro +108 -0
- package/src/routes/plan/briefs.astro +66 -0
- package/src/routes/plan/features/[id].astro +113 -0
- package/src/routes/plan/features/index.astro +29 -0
- package/src/routes/plan/inbox.astro +78 -0
- package/src/routes/plan/milestones/[milestone].astro +113 -0
- package/src/routes/plan/milestones/index.astro +56 -0
- package/src/routes/plan/now.astro +135 -0
- package/src/routes/plan/strategy.astro +194 -0
- package/src/scripts/plan.ts +40 -0
- package/src/styles/components.css +491 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- 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
|
-
#
|
|
1
|
+
# @purview-dev/pm-docs-site
|
|
2
2
|
|
|
3
|
-
|
|
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
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
|
+
});
|
package/dist/index.d.ts
ADDED
|
@@ -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;
|
package/dist/options.js
ADDED
|
@@ -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
|
+
}
|