@purview-dev/pm-docs-site 0.1.0-pre.1 → 0.1.0-pre.3
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/README.md +130 -18
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +91 -0
- package/dist/dev-env.d.ts +2 -0
- package/dist/dev-env.js +13 -0
- package/dist/fs-allow.d.ts +2 -0
- package/dist/fs-allow.js +11 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +152 -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 +27 -0
- package/dist/schema-version.js +48 -0
- package/dist/sidebar.d.ts +10 -0
- package/dist/sidebar.js +32 -0
- package/dist/site-options.d.ts +9 -0
- package/dist/site-options.js +44 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.js +4 -0
- package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
- package/lib/schema-version.ts +59 -0
- package/{index.d.ts → lib/types.ts} +5 -6
- package/package.json +19 -9
- package/src/components/FeatureSummary.astro +30 -9
- package/src/components/FeatureTable.astro +1 -1
- package/src/components/ItemDetail.astro +1 -1
- package/src/components/ItemDialog.astro +12 -8
- package/src/components/PlanInteractions.astro +15 -3
- package/src/components/RefLink.astro +7 -4
- package/src/components/board/Board.tsx +252 -0
- package/src/components/board/KanbanItemCard.tsx +131 -0
- package/src/components/board/LinkRuns.tsx +21 -0
- package/src/components/board/TaskKanbanCard.tsx +83 -0
- package/src/components/board/useBoardUrlState.ts +41 -0
- package/src/components/decisions/Decisions.tsx +162 -0
- package/src/components/decisions/useDecisionsUrlState.ts +29 -0
- package/src/components/graph/Graph.tsx +290 -0
- package/src/components/graph/GraphNodes.tsx +120 -0
- package/src/components/graph/useGraphUrlState.ts +58 -0
- package/src/components/lib/KanbanItemCard.astro +7 -11
- package/src/components/lib/StatusTimelineFeed.astro +3 -2
- package/src/components/lib/TaskKanbanCard.astro +2 -1
- package/src/components/timeline/Timeline.tsx +192 -0
- package/src/components/timeline/useTimelineLayout.ts +39 -0
- package/src/content.config.ts +22 -6
- package/src/env.d.ts +2 -2
- package/src/lib/board-data.ts +84 -0
- package/src/lib/board.ts +209 -0
- package/src/lib/decisions.ts +100 -0
- package/src/lib/graph-layout.ts +270 -0
- package/src/lib/graph-state.ts +99 -0
- package/src/lib/graph.ts +194 -0
- package/src/lib/link-html.ts +39 -0
- package/src/lib/planning-types.ts +32 -3
- package/src/lib/planning.ts +94 -52
- package/src/lib/ref-boundary.ts +19 -0
- package/src/lib/references.ts +67 -8
- package/src/lib/timeline-state.ts +119 -0
- package/src/lib/timeline.ts +51 -0
- package/src/loaders/adrs.ts +43 -0
- package/src/loaders/repo-docs.ts +3 -3
- package/src/pages/404.astro +18 -0
- package/src/pages/index.astro +1 -1
- package/src/pages/plan/board.astro +14 -113
- package/src/pages/plan/log.astro +18 -1
- package/src/pages/plan/roadmap.astro +21 -3
- package/src/routes/plan/decisions/[id].astro +93 -0
- package/src/routes/plan/decisions.astro +52 -0
- package/src/routes/plan/graph.astro +80 -0
- package/src/routes/plan/milestones/index.astro +2 -2
- package/src/routes/plan/now.astro +2 -3
- package/src/scripts/plan.ts +32 -46
- package/src/styles/components.css +244 -13
- package/src/styles/graph.css +296 -0
- package/src/styles/kanban.css +277 -0
- package/src/styles/timeline.css +210 -0
- package/cli.mjs +0 -120
- package/index.mjs +0 -97
- package/lib/options.mjs +0 -67
- package/lib/schema-version.mjs +0 -29
- package/lib/sidebar.mjs +0 -47
- package/lib/site-options.mjs +0 -38
package/README.md
CHANGED
|
@@ -8,15 +8,20 @@ optionally, the repository's Markdown, rendered by Astro and Starlight.
|
|
|
8
8
|
on purview.dev (the *Docs-site package* guide page), part of the
|
|
9
9
|
[PM Skills](https://purview.dev/projects/pm-skills/) project.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
`pm-docs-site` skill's
|
|
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.
|
|
14
15
|
|
|
15
16
|
## A consumer site
|
|
16
17
|
|
|
17
|
-
Three files: `package.json`, a lockfile, and `astro.config.
|
|
18
|
+
Three files: `package.json`, a lockfile, and `astro.config.ts`. No `src/`
|
|
18
19
|
folder: the integration points Astro's `srcDir` at the package.
|
|
19
20
|
|
|
21
|
+
On Windows, keep the site and the installed package on the same drive: Astro
|
|
22
|
+
cannot build a site whose root is on another drive than the package's `src/`,
|
|
23
|
+
so a package linked from another drive fails the build.
|
|
24
|
+
|
|
20
25
|
```json
|
|
21
26
|
{
|
|
22
27
|
"name": "my-project-site",
|
|
@@ -27,12 +32,12 @@ folder: the integration points Astro's `srcDir` at the package.
|
|
|
27
32
|
"build": "pm-docs-site build",
|
|
28
33
|
"check": "pm-docs-site check"
|
|
29
34
|
},
|
|
30
|
-
"dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.
|
|
35
|
+
"dependencies": { "@purview-dev/pm-docs-site": "0.1.0-pre.3" }
|
|
31
36
|
}
|
|
32
37
|
```
|
|
33
38
|
|
|
34
|
-
```
|
|
35
|
-
// astro.config.
|
|
39
|
+
```ts
|
|
40
|
+
// astro.config.ts
|
|
36
41
|
import pmDocsSite from '@purview-dev/pm-docs-site';
|
|
37
42
|
|
|
38
43
|
export default {
|
|
@@ -57,27 +62,133 @@ export default {
|
|
|
57
62
|
| `description` | string | none |
|
|
58
63
|
| `planning` | path from the site root | `../planning/planning.json` |
|
|
59
64
|
| `docs` | `{ root, sources }`; `root` from the site root, each source a folder and globs | none: no repository pages |
|
|
60
|
-
| `views` | any of `now`, `milestones`, `features`, `inbox`, `briefs`, `strategy` | all
|
|
65
|
+
| `views` | any of `now`, `milestones`, `graph`, `features`, `inbox`, `briefs`, `strategy`, `decisions` | all eight |
|
|
61
66
|
|
|
62
67
|
Home, Board, Roadmap, Log and Risks are always rendered. A docs source has
|
|
63
68
|
`label`, `base`, `include`, and optionally `prefix`, `indexFile`, `order`,
|
|
64
|
-
`collapsed`, and `hidden` (see `
|
|
69
|
+
`collapsed`, and `hidden` (see `lib/types.ts`).
|
|
70
|
+
|
|
71
|
+
## Board
|
|
72
|
+
|
|
73
|
+
The Board is a React island, hydrated on load: every roadmap item in five
|
|
74
|
+
columns (Now, Next, For you, Waiting, Done), filtered and grouped without a
|
|
75
|
+
page reload.
|
|
76
|
+
|
|
77
|
+
| Filter | Values |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Owner | `agent`, `user`, `both` |
|
|
80
|
+
| Milestone | each milestone in the plan, or `none` (no milestone) |
|
|
81
|
+
| Size | `S`, `M`, `L` |
|
|
82
|
+
| RAG | `red`, `amber`, `green`, or `none` (no risk) |
|
|
83
|
+
|
|
84
|
+
Filters combine with AND. A card's RAG is the worst of the open, mitigating,
|
|
85
|
+
or accepted risks that affect it (closed risks and milestone-level risks
|
|
86
|
+
never colour a card). Group by `none` (today's board), `milestone`, or
|
|
87
|
+
`owner`, which splits the board into one lane per group, each holding all
|
|
88
|
+
five columns.
|
|
89
|
+
|
|
90
|
+
Filter and group state lives in the URL query string, in that order
|
|
91
|
+
(`owner`, `milestone`, `size`, `rag`, `group`), so a filtered or grouped
|
|
92
|
+
board can be linked and survives a reload:
|
|
93
|
+
`/plan/board/?owner=user&milestone=M2&group=milestone`. Unknown or junk
|
|
94
|
+
values fall back to All / None. Column collapse still works per column,
|
|
95
|
+
across every lane, and without JavaScript the full, ungrouped board renders
|
|
96
|
+
with the filter bar hidden; the column collapse toggles appear only once
|
|
97
|
+
the island loads.
|
|
98
|
+
|
|
99
|
+
The integration adds `@astrojs/react` itself, so a consumer site stays the
|
|
100
|
+
three files above.
|
|
101
|
+
|
|
102
|
+
## Roadmap timeline
|
|
103
|
+
|
|
104
|
+
The Roadmap page opens with a timeline: a React island with one card per
|
|
105
|
+
milestone, in strategy order, then a `No milestone` card when it has items
|
|
106
|
+
that are not dropped. Each card shows the milestone ID and name (a link to
|
|
107
|
+
its milestone page when the Milestones view is on), a `Focus` badge, its
|
|
108
|
+
status (with the done date), its target or `No target`, and
|
|
109
|
+
`<done> of <total> done` with a progress bar.
|
|
110
|
+
|
|
111
|
+
The strip runs left to right by default and scrolls sideways inside itself;
|
|
112
|
+
a plain vertical wheel scrolls it sideways until it reaches an end, then
|
|
113
|
+
the page scrolls. `Top to bottom` lays it out vertically, and the choice is
|
|
114
|
+
kept in the URL as `?layout=vertical`, alongside any other parameters, so a
|
|
115
|
+
link opens the same layout.
|
|
116
|
+
|
|
117
|
+
Zoom runs from 50% to 200% in steps of 25%: the `Zoom out`, `Zoom in`, and
|
|
118
|
+
`Reset zoom` buttons, Ctrl or Cmd + wheel over the strip, or a trackpad
|
|
119
|
+
pinch. Zoom resizes the cards rather than scaling the page, and it is not
|
|
120
|
+
kept in the URL: every visit starts at 100%.
|
|
121
|
+
|
|
122
|
+
## Graph
|
|
123
|
+
|
|
124
|
+
The Graph page (the `graph` view) is a React island that shows how open
|
|
125
|
+
items depend on each other: one node per open item, with its ID (a link to
|
|
126
|
+
its feature page), title, milestone, size, section, and owner, and one edge
|
|
127
|
+
per `Depends on` and `Revisits` link, drawn from the prerequisite to the item
|
|
128
|
+
that waits for it and left to right in the order the work has to happen.
|
|
129
|
+
`Revisits` edges are dashed and labelled `revisits`. A done or dropped item
|
|
130
|
+
an open item points at is a small chip (`✓ R-008`, or `✗ R-003` struck
|
|
131
|
+
through), and an ID that matches no item is a warning chip
|
|
132
|
+
(`? R-099 not found`). The active item is highlighted as on the Board; an
|
|
133
|
+
explicitly blocked item has a dashed border. Every position is computed at
|
|
134
|
+
build time, so no layout code reaches the browser.
|
|
135
|
+
|
|
136
|
+
Two switches change the view, and each is kept in the URL alongside any
|
|
137
|
+
other parameters:
|
|
138
|
+
|
|
139
|
+
| Switch | Off | URL key |
|
|
140
|
+
| --- | --- | --- |
|
|
141
|
+
| `Milestone lanes` | one flow, with unlinked items in a `No links` tray below | `lanes=off` |
|
|
142
|
+
| `Show done prerequisites` | no done or dropped chips; each node shows `✓ <n> done` instead | `done=off` |
|
|
143
|
+
|
|
144
|
+
With lanes on, each milestone with open items is a band, in strategy order,
|
|
145
|
+
labelled with its ID and name and `Focus` for the focus milestone, then
|
|
146
|
+
`No milestone`. Click a node or chip, or press Enter on it, to trace its
|
|
147
|
+
chain: everything it waits on and everything that waits on it, transitively,
|
|
148
|
+
stays bright and the rest fades. The selection is kept as `focus=<ID>`, so
|
|
149
|
+
a link opens with the same chain highlighted. Click the selected node again,
|
|
150
|
+
or its ID link, to open its feature page; Escape or a click on the
|
|
151
|
+
background clears the selection. Drag to pan, and zoom with the wheel or a
|
|
152
|
+
pinch over the graph, or the `Zoom out`, `Zoom in`, and `Fit` buttons.
|
|
153
|
+
|
|
154
|
+
Below the graph, a `Dependencies` list gives each open item's links as plain
|
|
155
|
+
text, for search, screen readers, and browsers without JavaScript.
|
|
156
|
+
|
|
157
|
+
The page adds `@xyflow/react` and `@dagrejs/dagre` as dependencies; dagre
|
|
158
|
+
runs at build time only; it never reaches the browser. The island's
|
|
159
|
+
JavaScript and `graph.css` load only on `/plan/graph/`, never on another page.
|
|
160
|
+
|
|
161
|
+
## Decisions
|
|
162
|
+
|
|
163
|
+
The Decisions page lists the architecture decision records in the export's
|
|
164
|
+
`adrs` (written by `pm-export` from `<PM root>/decisions/`) as a React
|
|
165
|
+
island: a search box over each ADR's ID, title, category, and text, status
|
|
166
|
+
chips (superseded is off by default), category chips, and `Group by`
|
|
167
|
+
category, status, or none. The state is kept in the URL, so a filtered
|
|
168
|
+
view can be shared; `Clear` returns to the default. Every ADR has its own
|
|
169
|
+
page with its header fields and its Context, Decision, Alternatives, and
|
|
170
|
+
Consequences rendered from Markdown, and search indexes it. A feature page
|
|
171
|
+
lists the ADRs whose `Item` is that item.
|
|
65
172
|
|
|
66
173
|
## CLI
|
|
67
174
|
|
|
68
|
-
The CLI runs under Node
|
|
175
|
+
The CLI runs under Node 24 or later.
|
|
69
176
|
|
|
70
177
|
- `pm-docs-site build [site-dir]` and `pm-docs-site dev [site-dir]` run Astro
|
|
71
178
|
on the site. A site with no `astro.config.*` builds from
|
|
72
|
-
`--title <title>` and `--planning <path>`.
|
|
179
|
+
`--title <title>` and `--planning <path>`. A site with an `astro.config.*`
|
|
180
|
+
takes its options from that file: the flags are ignored, with a warning.
|
|
181
|
+
`dev` turns off Astro's update check (`ASTRO_DISABLE_UPDATE_CHECK=true`):
|
|
182
|
+
this package pins Astro, and the check's settings write can restart the
|
|
183
|
+
dev server while it starts. Set the variable yourself to keep the check.
|
|
73
184
|
- `pm-docs-site check [site-dir]` builds nothing. It reads the export, checks
|
|
74
185
|
its `schemaVersion`, and checks every docs source folder exists, then exits
|
|
75
186
|
0, or 1 with one line per problem.
|
|
76
187
|
|
|
77
188
|
## Supported exports
|
|
78
189
|
|
|
79
|
-
`SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.
|
|
80
|
-
`schemaVersion`
|
|
190
|
+
`SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.ts`: pm-export
|
|
191
|
+
`schemaVersion` 5. Any other version fails the build and `check`, and the
|
|
81
192
|
message says to run the `pm-export` skill.
|
|
82
193
|
|
|
83
194
|
## Development
|
|
@@ -123,10 +234,11 @@ the purview-dev release rules:
|
|
|
123
234
|
| REL003 | a stable version runs from `main` | fails |
|
|
124
235
|
|
|
125
236
|
While `package.json` sets `"private": true` it also skips, green. Then it
|
|
126
|
-
installs, tests, type-checks, and runs `scripts/check-exports.
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
237
|
+
installs, tests, type-checks, builds `dist/`, and runs `scripts/check-exports.ts`.
|
|
238
|
+
The `prepack` script runs the same build and check, so every pack and a local
|
|
239
|
+
`npm publish` build first and cannot burn a version on a package whose entry points
|
|
240
|
+
are missing or the wrong kind of file. It publishes a prerelease
|
|
241
|
+
version (one with a `-pre` part) under the `prerelease` dist-tag and a stable version under
|
|
130
242
|
`latest`, skips a version already on the registry, and keeps `latest` on the
|
|
131
243
|
newest prerelease until a stable release exists. Only then does it create the
|
|
132
244
|
tag and a GitHub release, never marked as the repository's latest release.
|
|
@@ -147,7 +259,7 @@ environment.
|
|
|
147
259
|
A trusted publisher is configured on the package, so the package must exist
|
|
148
260
|
on npm first. Once, from an account that can publish to `@purview-dev`:
|
|
149
261
|
|
|
150
|
-
1. Remove `"private": true`, set
|
|
262
|
+
1. Remove `"private": true`, set a prerelease version, and
|
|
151
263
|
publish it locally: `npm publish --access public --tag prerelease`.
|
|
152
264
|
2. Add the trusted publisher, with *Allow npm publish* and *Allow npm
|
|
153
265
|
dist-tag* ticked (the CLI grants only the first):
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
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 { disableUpdateCheck } from "./dev-env.js";
|
|
10
|
+
import { resolveOptions } from "./options.js";
|
|
11
|
+
import { parseExport } from "./schema-version.js";
|
|
12
|
+
import { loadSiteOptions } from "./site-options.js";
|
|
13
|
+
const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
|
|
14
|
+
function parse(argv) {
|
|
15
|
+
const flags = {};
|
|
16
|
+
const positional = [];
|
|
17
|
+
for (let index = 0; index < argv.length; index++) {
|
|
18
|
+
const arg = argv[index];
|
|
19
|
+
if (arg === '--title' || arg === '--planning') {
|
|
20
|
+
const value = argv[++index];
|
|
21
|
+
if (value === undefined)
|
|
22
|
+
throw new Error(`pm-docs-site: ${arg} needs a value`);
|
|
23
|
+
flags[arg === '--title' ? 'title' : 'planning'] = value;
|
|
24
|
+
}
|
|
25
|
+
else {
|
|
26
|
+
positional.push(arg);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return { command: positional[0], siteDir: resolve(positional[1] ?? process.cwd()), flags };
|
|
30
|
+
}
|
|
31
|
+
/** The problems check finds, one line each. */
|
|
32
|
+
function problems(options) {
|
|
33
|
+
const found = [];
|
|
34
|
+
if (!existsSync(options.planning)) {
|
|
35
|
+
found.push(`No plan export at ${options.planning}. Run the pm-export skill to write planning.json.`);
|
|
36
|
+
}
|
|
37
|
+
else {
|
|
38
|
+
try {
|
|
39
|
+
parseExport(readFileSync(options.planning, 'utf8'), 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
|
+
disableUpdateCheck(process.env);
|
|
81
|
+
await astro.dev(inline);
|
|
82
|
+
// The dev server keeps the process alive until it is stopped.
|
|
83
|
+
return null;
|
|
84
|
+
}
|
|
85
|
+
main().then((code) => {
|
|
86
|
+
if (code !== null)
|
|
87
|
+
process.exitCode = code;
|
|
88
|
+
}, (error) => {
|
|
89
|
+
console.error(error instanceof Error ? error.message : error);
|
|
90
|
+
process.exitCode = 1;
|
|
91
|
+
});
|
package/dist/dev-env.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// The environment `pm-docs-site dev` runs Astro in.
|
|
2
|
+
//
|
|
3
|
+
// Astro's dev server checks npm for a newer Astro on start (not on CI) and
|
|
4
|
+
// records the check in `.astro/settings.json`. It ignores one watcher event for
|
|
5
|
+
// that write, but on Windows a new file gives two (create, then change), so the
|
|
6
|
+
// second restarts the server; a restart while it starts cuts the content sync,
|
|
7
|
+
// and every page then answers 500 until it is restarted by hand (R-029). The
|
|
8
|
+
// package pins Astro, so the notice is not the consumer's to act on: turn the
|
|
9
|
+
// check off unless the consumer has set ASTRO_DISABLE_UPDATE_CHECK.
|
|
10
|
+
/** Sets ASTRO_DISABLE_UPDATE_CHECK to `true` in `env` when it is unset. */
|
|
11
|
+
export function disableUpdateCheck(env) {
|
|
12
|
+
env.ASTRO_DISABLE_UPDATE_CHECK ??= 'true';
|
|
13
|
+
}
|
package/dist/fs-allow.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// Whether a Vite `server.fs.allow` entry already covers a path: the in-repo
|
|
2
|
+
// fixture and linked consumers resolve this package outside the site's
|
|
3
|
+
// workspace root, so the integration allows the package folder only when no
|
|
4
|
+
// entry contains it.
|
|
5
|
+
import { isAbsolute, relative, sep } from 'node:path';
|
|
6
|
+
/** Whether `path` is `entry` or inside it. Separators, drives and case follow `node:path`. */
|
|
7
|
+
export function containsPath(entry, path) {
|
|
8
|
+
const rel = relative(entry, path);
|
|
9
|
+
const escapes = rel === '..' || rel.startsWith(`..${sep}`);
|
|
10
|
+
return !escapes && !isAbsolute(rel);
|
|
11
|
+
}
|
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,152 @@
|
|
|
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, realpathSync } 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 { containsPath } from "./fs-allow.js";
|
|
13
|
+
import { resolveOptions } from "./options.js";
|
|
14
|
+
import { buildSidebar } from "./sidebar.js";
|
|
15
|
+
/**
|
|
16
|
+
* The pages each optional view owns, in src/routes/ so Astro routes them only
|
|
17
|
+
* when the view is on. Home, Board, Roadmap, Log and Risks are in src/pages/.
|
|
18
|
+
*/
|
|
19
|
+
const VIEW_ROUTES = {
|
|
20
|
+
now: [['/plan/now', 'plan/now.astro']],
|
|
21
|
+
milestones: [
|
|
22
|
+
['/plan/milestones', 'plan/milestones/index.astro'],
|
|
23
|
+
['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
|
|
24
|
+
],
|
|
25
|
+
graph: [['/plan/graph', 'plan/graph.astro']],
|
|
26
|
+
features: [
|
|
27
|
+
['/plan/features', 'plan/features/index.astro'],
|
|
28
|
+
['/plan/features/[id]', 'plan/features/[id].astro'],
|
|
29
|
+
],
|
|
30
|
+
inbox: [['/plan/inbox', 'plan/inbox.astro']],
|
|
31
|
+
briefs: [['/plan/briefs', 'plan/briefs.astro']],
|
|
32
|
+
strategy: [['/plan/strategy', 'plan/strategy.astro']],
|
|
33
|
+
decisions: [
|
|
34
|
+
['/plan/decisions', 'plan/decisions.astro'],
|
|
35
|
+
['/plan/decisions/[id]', 'plan/decisions/[id].astro'],
|
|
36
|
+
],
|
|
37
|
+
};
|
|
38
|
+
const PACKAGE_NAME = '@purview-dev/pm-docs-site';
|
|
39
|
+
/**
|
|
40
|
+
* The package folder, real path, with forward slashes as Vite stores its
|
|
41
|
+
* `server.fs.allow` entries. lib/index.ts (in this repository) and
|
|
42
|
+
* dist/index.js (installed) both sit one level below it.
|
|
43
|
+
*/
|
|
44
|
+
const PACKAGE_DIR = realpathSync(fileURLToPath(new URL('../', import.meta.url))).replaceAll('\\', '/');
|
|
45
|
+
const REACT_INTEGRATION = '@astrojs/react';
|
|
46
|
+
const NO_EXTERNAL = ['@astrojs/starlight', PACKAGE_NAME];
|
|
47
|
+
const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
|
|
48
|
+
/**
|
|
49
|
+
* Whether `name` is installed in a node_modules folder at or above `root`,
|
|
50
|
+
* walked as Vite resolves it: under Bun, `createRequire` also finds Bun's
|
|
51
|
+
* global cache, which Vite never looks in.
|
|
52
|
+
*/
|
|
53
|
+
function resolvesFrom(name, root) {
|
|
54
|
+
for (let dir = resolve(root);; dir = dirname(dir)) {
|
|
55
|
+
if (existsSync(join(dir, 'node_modules', name, 'package.json')))
|
|
56
|
+
return true;
|
|
57
|
+
if (dirname(dir) === dir)
|
|
58
|
+
return false;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
/** The islands' dependencies Vite's dev optimizer must pre-bundle (optimizedDependencies). */
|
|
62
|
+
const BROWSER_DEPENDENCIES = ['react-dom/client', '@xyflow/react'];
|
|
63
|
+
/**
|
|
64
|
+
* The `optimizeDeps.include` entries the site lacks. The island's renderer
|
|
65
|
+
* (@astrojs/react-renderer) imports react-dom/client from under node_modules,
|
|
66
|
+
* which Vite's dev optimizer skips, so React's CommonJS reaches the browser
|
|
67
|
+
* raw and the Board never hydrates. An installed package is pre-bundled
|
|
68
|
+
* through itself (`<package> > react-dom/client`); a site that cannot resolve
|
|
69
|
+
* the package by name (this repository's fixtures) names react-dom/client
|
|
70
|
+
* plainly, since naming a package Vite cannot resolve breaks the optimizer.
|
|
71
|
+
* The Graph island's @xyflow/react is imported from this package's own source
|
|
72
|
+
* under node_modules, which the optimizer does not scan either, and its
|
|
73
|
+
* react-compiler-runtime dependency is CommonJS, so it is pre-bundled the same
|
|
74
|
+
* way. Only missing entries: Vite's mergeConfig concatenates arrays.
|
|
75
|
+
*/
|
|
76
|
+
function optimizedDependencies(include, root) {
|
|
77
|
+
const existing = Array.isArray(include) ? include : [];
|
|
78
|
+
const viaPackage = resolvesFrom(PACKAGE_NAME, root);
|
|
79
|
+
return BROWSER_DEPENDENCIES.map((name) => (viaPackage ? `${PACKAGE_NAME} > ${name}` : name)).filter((entry) => !existing.includes(entry));
|
|
80
|
+
}
|
|
81
|
+
const VIRTUAL_ID = 'virtual:pm-docs-site/config';
|
|
82
|
+
const RESOLVED_ID = `\0${VIRTUAL_ID}`;
|
|
83
|
+
/** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
|
|
84
|
+
export default function pmDocsSite(options) {
|
|
85
|
+
return {
|
|
86
|
+
name: 'pm-docs-site',
|
|
87
|
+
pmDocsSiteOptions: options,
|
|
88
|
+
hooks: {
|
|
89
|
+
'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
|
|
90
|
+
const root = fileURLToPath(config.root);
|
|
91
|
+
const resolved = resolveOptions(options, root);
|
|
92
|
+
// A consumer that adds React itself keeps its own: two would register the renderer twice.
|
|
93
|
+
const hasReact = (config.integrations ?? []).some((integration) => integration.name === REACT_INTEGRATION);
|
|
94
|
+
for (const [view, routes] of Object.entries(VIEW_ROUTES)) {
|
|
95
|
+
if (!resolved.views[view])
|
|
96
|
+
continue;
|
|
97
|
+
for (const [pattern, file] of routes) {
|
|
98
|
+
injectRoute({ pattern, entrypoint: new URL(`../src/routes/${file}`, import.meta.url) });
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
updateConfig({
|
|
102
|
+
srcDir: new URL('../src/', import.meta.url),
|
|
103
|
+
integrations: [
|
|
104
|
+
starlight({
|
|
105
|
+
title: resolved.title,
|
|
106
|
+
...(resolved.description ? { description: resolved.description } : {}),
|
|
107
|
+
sidebar: buildSidebar(resolved),
|
|
108
|
+
// src/pages/404.astro is the not-found page (it says why).
|
|
109
|
+
disable404Route: true,
|
|
110
|
+
// Every page uses the full width (src/styles/width.css).
|
|
111
|
+
customCss: [fileURLToPath(new URL('../src/styles/width.css', import.meta.url))],
|
|
112
|
+
}),
|
|
113
|
+
...(hasReact ? [] : [react()]),
|
|
114
|
+
],
|
|
115
|
+
vite: {
|
|
116
|
+
optimizeDeps: { include: optimizedDependencies(config.vite?.optimizeDeps?.include, root) },
|
|
117
|
+
plugins: [
|
|
118
|
+
{
|
|
119
|
+
name: 'pm-docs-site:config',
|
|
120
|
+
resolveId: (id) => (id === VIRTUAL_ID ? RESOLVED_ID : undefined),
|
|
121
|
+
load: (id) => (id === RESOLVED_ID ? `export default ${JSON.stringify(resolved)};` : undefined),
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
// Bundle Starlight and this package in every server environment, whatever
|
|
125
|
+
// the consumer's package.json lists: externalised, Starlight cannot import
|
|
126
|
+
// astro:middleware. Astro 7 renders static pages in its own `prerender`
|
|
127
|
+
// environment, which top-level `vite.ssr` does not reach.
|
|
128
|
+
name: 'pm-docs-site:no-external',
|
|
129
|
+
configEnvironment: (name) => SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
// Serve the package's own files in dev. The in-repo fixture and a linked
|
|
133
|
+
// consumer resolve the package outside the site's workspace root, so Vite
|
|
134
|
+
// refuses its node_modules (the React island client) and nothing hydrates.
|
|
135
|
+
// Append only: Vite's defaults and the consumer's entries stay. The entry
|
|
136
|
+
// serves the whole package folder in in-repo and linked dev; Vite's
|
|
137
|
+
// `server.fs.deny` still guards it. On a case-insensitive file system a
|
|
138
|
+
// path that differs only in case appends a second, harmless entry.
|
|
139
|
+
name: 'pm-docs-site:fs-allow',
|
|
140
|
+
configResolved: (resolvedConfig) => {
|
|
141
|
+
const { allow } = resolvedConfig.server.fs;
|
|
142
|
+
if (!allow.some((entry) => containsPath(entry, PACKAGE_DIR)))
|
|
143
|
+
allow.push(PACKAGE_DIR);
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
],
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
};
|
|
152
|
+
}
|
|
@@ -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', 'graph', 'features', 'inbox', 'briefs', 'strategy', 'decisions'];
|
|
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
|
+
};
|