@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
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
/* The Roadmap page's milestone timeline (src/components/timeline/Timeline.tsx).
|
|
2
|
+
Zoom is one custom property, --timeline-zoom, set on the strip: every size
|
|
3
|
+
below that should grow with it is written as calc(<base> * zoom), so text
|
|
4
|
+
stays sharp and the strip's scroll extent matches its content. Colours come
|
|
5
|
+
from Starlight's variables only, so light and dark themes both work. */
|
|
6
|
+
|
|
7
|
+
.plan-timeline {
|
|
8
|
+
margin-block: 1rem 2rem;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
.plan-timeline__toolbar {
|
|
12
|
+
display: flex;
|
|
13
|
+
flex-wrap: wrap;
|
|
14
|
+
gap: 0.5rem 1rem;
|
|
15
|
+
margin-bottom: 0.75rem;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
.plan-timeline__toolbar[hidden] {
|
|
19
|
+
display: none;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
.plan-timeline__group {
|
|
23
|
+
display: flex;
|
|
24
|
+
flex-wrap: wrap;
|
|
25
|
+
align-items: center;
|
|
26
|
+
gap: 0.25rem;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
.plan-timeline__toolbar button {
|
|
30
|
+
padding: 0.2rem 0.6rem;
|
|
31
|
+
border: 1px solid var(--sl-color-gray-5);
|
|
32
|
+
border-radius: 0.375rem;
|
|
33
|
+
background: var(--sl-color-bg);
|
|
34
|
+
color: var(--sl-color-text);
|
|
35
|
+
font-size: var(--sl-text-sm);
|
|
36
|
+
cursor: pointer;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
.plan-timeline__toolbar button[aria-pressed='true'] {
|
|
40
|
+
border-color: var(--sl-color-accent);
|
|
41
|
+
background: var(--sl-color-accent-low);
|
|
42
|
+
color: var(--sl-color-accent-high);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
.plan-timeline__toolbar button[aria-disabled='true'] {
|
|
46
|
+
cursor: default;
|
|
47
|
+
opacity: 0.5;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
.plan-timeline__zoom {
|
|
51
|
+
min-width: 3.5em;
|
|
52
|
+
color: var(--sl-color-gray-2);
|
|
53
|
+
font-size: var(--sl-text-sm);
|
|
54
|
+
font-variant-numeric: tabular-nums;
|
|
55
|
+
text-align: center;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/* The sizes are declared here, where --timeline-zoom is set, so they follow it. */
|
|
59
|
+
.plan-timeline__strip {
|
|
60
|
+
--timeline-gap: calc(1.5rem * var(--timeline-zoom, 1));
|
|
61
|
+
--timeline-pad: calc(0.75rem * var(--timeline-zoom, 1));
|
|
62
|
+
--timeline-marker: calc(0.75rem * var(--timeline-zoom, 1));
|
|
63
|
+
|
|
64
|
+
position: relative;
|
|
65
|
+
display: flex;
|
|
66
|
+
gap: var(--timeline-gap);
|
|
67
|
+
margin: 0;
|
|
68
|
+
padding: 0.25rem;
|
|
69
|
+
list-style: none;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
.plan-timeline__strip:focus-visible {
|
|
73
|
+
outline: 2px solid var(--sl-color-accent);
|
|
74
|
+
outline-offset: 2px;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/* Left to right: one row of a fixed height, scrolling sideways inside itself. */
|
|
78
|
+
.plan-timeline__strip[data-layout='horizontal'] {
|
|
79
|
+
flex-wrap: nowrap;
|
|
80
|
+
align-items: stretch;
|
|
81
|
+
overflow-x: auto;
|
|
82
|
+
overflow-y: hidden;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/* Top to bottom: no height limit and no scroll box, so the page's own scroll moves through it. */
|
|
86
|
+
.plan-timeline__strip[data-layout='vertical'] {
|
|
87
|
+
flex-direction: column;
|
|
88
|
+
align-items: flex-start;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
.plan-timeline__card {
|
|
92
|
+
position: relative;
|
|
93
|
+
box-sizing: border-box;
|
|
94
|
+
flex: 0 0 auto;
|
|
95
|
+
width: calc(14rem * var(--timeline-zoom, 1));
|
|
96
|
+
margin: 0;
|
|
97
|
+
padding: var(--timeline-pad);
|
|
98
|
+
border: 1px solid var(--sl-color-hairline);
|
|
99
|
+
border-radius: calc(0.5rem * var(--timeline-zoom, 1));
|
|
100
|
+
background: var(--sl-color-bg-nav);
|
|
101
|
+
color: var(--sl-color-text);
|
|
102
|
+
font-size: calc(var(--sl-text-sm) * var(--timeline-zoom, 1));
|
|
103
|
+
line-height: 1.4;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.plan-timeline__strip[data-layout='vertical'] .plan-timeline__card {
|
|
107
|
+
max-width: 100%;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/* The connector: a line from the previous card's marker to this one's. */
|
|
111
|
+
.plan-timeline__card + .plan-timeline__card::before {
|
|
112
|
+
position: absolute;
|
|
113
|
+
content: '';
|
|
114
|
+
background: var(--sl-color-gray-4);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
.plan-timeline__strip[data-layout='horizontal'] .plan-timeline__card + .plan-timeline__card::before {
|
|
118
|
+
top: calc(var(--timeline-pad) + var(--timeline-marker) / 2 - 1px);
|
|
119
|
+
left: calc(-1 * var(--timeline-gap) - 1px);
|
|
120
|
+
width: var(--timeline-gap);
|
|
121
|
+
height: 2px;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
.plan-timeline__strip[data-layout='vertical'] .plan-timeline__card + .plan-timeline__card::before {
|
|
125
|
+
top: calc(-1 * var(--timeline-gap) - 1px);
|
|
126
|
+
left: calc(var(--timeline-pad) + var(--timeline-marker) / 2 - 1px);
|
|
127
|
+
width: 2px;
|
|
128
|
+
height: var(--timeline-gap);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/* The marker, by state: filled for done, ringed and accented for active, hollow for planned and any other status. */
|
|
132
|
+
.plan-timeline__marker {
|
|
133
|
+
display: block;
|
|
134
|
+
box-sizing: border-box;
|
|
135
|
+
width: var(--timeline-marker);
|
|
136
|
+
height: var(--timeline-marker);
|
|
137
|
+
margin-bottom: calc(0.5rem * var(--timeline-zoom, 1));
|
|
138
|
+
border: 2px solid var(--sl-color-gray-3);
|
|
139
|
+
border-radius: 50%;
|
|
140
|
+
background: transparent;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
.plan-timeline__card[data-state='done'] .plan-timeline__marker {
|
|
144
|
+
border-color: var(--sl-color-gray-2);
|
|
145
|
+
background: var(--sl-color-gray-2);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
.plan-timeline__card[data-state='active'] .plan-timeline__marker {
|
|
149
|
+
border-color: var(--sl-color-accent);
|
|
150
|
+
background: var(--sl-color-bg);
|
|
151
|
+
box-shadow: 0 0 0 3px var(--sl-color-accent-low);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
.plan-timeline__card p {
|
|
155
|
+
margin: 0;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
.plan-timeline__card p + p,
|
|
159
|
+
.plan-timeline__bar {
|
|
160
|
+
margin-top: calc(0.25rem * var(--timeline-zoom, 1));
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
.plan-timeline__title {
|
|
164
|
+
font-weight: 600;
|
|
165
|
+
overflow-wrap: anywhere;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
.plan-timeline__title a {
|
|
169
|
+
color: var(--sl-color-text-accent);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
.plan-timeline__focus {
|
|
173
|
+
margin-left: 0.4em;
|
|
174
|
+
padding: 0.05em 0.5em;
|
|
175
|
+
border-radius: 999px;
|
|
176
|
+
background: var(--sl-color-accent-low);
|
|
177
|
+
color: var(--sl-color-accent-high);
|
|
178
|
+
font-size: 0.85em;
|
|
179
|
+
font-weight: 400;
|
|
180
|
+
white-space: nowrap;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
.plan-timeline__status,
|
|
184
|
+
.plan-timeline__target,
|
|
185
|
+
.plan-timeline__count {
|
|
186
|
+
color: var(--sl-color-gray-2);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
.plan-timeline__bar {
|
|
190
|
+
display: block;
|
|
191
|
+
width: 100%;
|
|
192
|
+
height: calc(0.5rem * var(--timeline-zoom, 1));
|
|
193
|
+
accent-color: var(--sl-color-accent);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/* While <html> has the pending mark (`?layout=vertical`, the inline script in
|
|
197
|
+
roadmap.astro) the strip is hidden until the island has rendered the
|
|
198
|
+
vertical layout, so a vertical link never flashes horizontal. If the island
|
|
199
|
+
never loads and so never clears the mark, the strip shows anyway after 3s,
|
|
200
|
+
horizontally: never a blank strip. */
|
|
201
|
+
:root[data-timeline-pending] .plan-timeline__strip {
|
|
202
|
+
visibility: hidden;
|
|
203
|
+
animation: plan-timeline-reveal 0s 3s forwards;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
@keyframes plan-timeline-reveal {
|
|
207
|
+
to {
|
|
208
|
+
visibility: visible;
|
|
209
|
+
}
|
|
210
|
+
}
|
package/cli.mjs
DELETED
|
@@ -1,120 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
// @ts-check
|
|
3
|
-
// pm-docs-site <dev | build | check> [site-dir] [--title <t>] [--planning <p>]
|
|
4
|
-
//
|
|
5
|
-
// dev and build run Astro on the site folder: with its astro.config file when it
|
|
6
|
-
// has one, else with the integration built from --title and --planning. check
|
|
7
|
-
// builds nothing: it reads the export and the docs sources and reports problems.
|
|
8
|
-
|
|
9
|
-
import { existsSync, readFileSync } from 'node:fs';
|
|
10
|
-
import { resolve } from 'node:path';
|
|
11
|
-
|
|
12
|
-
import { resolveOptions } from './lib/options.mjs';
|
|
13
|
-
import { checkSchemaVersion } from './lib/schema-version.mjs';
|
|
14
|
-
import { loadSiteOptions } from './lib/site-options.mjs';
|
|
15
|
-
|
|
16
|
-
const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
|
|
17
|
-
|
|
18
|
-
/**
|
|
19
|
-
* @param {string[]} argv
|
|
20
|
-
* @returns {{ command: string | undefined; siteDir: string; flags: { title?: string; planning?: string } }}
|
|
21
|
-
*/
|
|
22
|
-
function parse(argv) {
|
|
23
|
-
/** @type {{ title?: string; planning?: string }} */
|
|
24
|
-
const flags = {};
|
|
25
|
-
/** @type {string[]} */
|
|
26
|
-
const positional = [];
|
|
27
|
-
|
|
28
|
-
for (let index = 0; index < argv.length; index++) {
|
|
29
|
-
const arg = /** @type {string} */ (argv[index]);
|
|
30
|
-
|
|
31
|
-
if (arg === '--title' || arg === '--planning') {
|
|
32
|
-
const value = argv[++index];
|
|
33
|
-
if (value === undefined) throw new Error(`pm-docs-site: ${arg} needs a value`);
|
|
34
|
-
flags[arg === '--title' ? 'title' : 'planning'] = value;
|
|
35
|
-
} else {
|
|
36
|
-
positional.push(arg);
|
|
37
|
-
}
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
return { command: positional[0], siteDir: resolve(positional[1] ?? process.cwd()), flags };
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
/**
|
|
44
|
-
* The problems check finds, one line each.
|
|
45
|
-
* @param {import('./index').ResolvedOptions} options
|
|
46
|
-
* @returns {string[]}
|
|
47
|
-
*/
|
|
48
|
-
function problems(options) {
|
|
49
|
-
/** @type {string[]} */
|
|
50
|
-
const found = [];
|
|
51
|
-
|
|
52
|
-
if (!existsSync(options.planning)) {
|
|
53
|
-
found.push(`No plan export at ${options.planning}. Run the pm-export skill to write planning.json.`);
|
|
54
|
-
} else {
|
|
55
|
-
try {
|
|
56
|
-
const planning = JSON.parse(readFileSync(options.planning, 'utf8'));
|
|
57
|
-
checkSchemaVersion(planning.schemaVersion, options.planning);
|
|
58
|
-
} catch (error) {
|
|
59
|
-
found.push(/** @type {Error} */ (error).message);
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
for (const source of options.docs?.sources ?? []) {
|
|
64
|
-
const base = resolve(options.docs?.root ?? '.', source.base);
|
|
65
|
-
if (!existsSync(base)) found.push(`docs source "${source.label}": no folder at ${base}`);
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
return found;
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
async function main() {
|
|
72
|
-
const { command, siteDir, flags } = parse(process.argv.slice(2));
|
|
73
|
-
|
|
74
|
-
if (command !== 'dev' && command !== 'build' && command !== 'check') {
|
|
75
|
-
console.error(USAGE);
|
|
76
|
-
return 2;
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
const { options, configFile } = await loadSiteOptions(siteDir, flags);
|
|
80
|
-
|
|
81
|
-
if (command === 'check') {
|
|
82
|
-
const resolved = resolveOptions(options, siteDir);
|
|
83
|
-
const found = problems(resolved);
|
|
84
|
-
|
|
85
|
-
for (const line of found) console.error(`pm-docs-site: ${line}`);
|
|
86
|
-
if (found.length) return 1;
|
|
87
|
-
|
|
88
|
-
const { schemaVersion } = JSON.parse(readFileSync(resolved.planning, 'utf8'));
|
|
89
|
-
console.log(`pm-docs-site: ok (${resolved.planning}, schemaVersion ${schemaVersion})`);
|
|
90
|
-
return 0;
|
|
91
|
-
}
|
|
92
|
-
|
|
93
|
-
const astro = await import('astro');
|
|
94
|
-
/** @type {import('astro').AstroInlineConfig} */
|
|
95
|
-
const inline = { root: siteDir };
|
|
96
|
-
|
|
97
|
-
if (!configFile) {
|
|
98
|
-
const { default: pmDocsSite } = await import('./index.mjs');
|
|
99
|
-
Object.assign(inline, { configFile: false, integrations: [pmDocsSite(options)] });
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
if (command === 'build') {
|
|
103
|
-
await astro.build(inline);
|
|
104
|
-
return 0;
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
await astro.dev(inline);
|
|
108
|
-
// The dev server keeps the process alive until it is stopped.
|
|
109
|
-
return null;
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
main().then(
|
|
113
|
-
(code) => {
|
|
114
|
-
if (code !== null) process.exitCode = code;
|
|
115
|
-
},
|
|
116
|
-
(error) => {
|
|
117
|
-
console.error(error instanceof Error ? error.message : error);
|
|
118
|
-
process.exitCode = 1;
|
|
119
|
-
},
|
|
120
|
-
);
|
package/index.mjs
DELETED
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
// @ts-check
|
|
2
|
-
// The pm-docs-site Astro integration. The consumer's astro.config.mjs holds
|
|
3
|
-
// only `integrations: [pmDocsSite({ title, ... })]`: this points Astro's srcDir
|
|
4
|
-
// at the package's own src/ (pages, components, content config), adds
|
|
5
|
-
// Starlight with the plan sidebar, and serves the resolved options to the pages
|
|
6
|
-
// as `virtual:pm-docs-site/config`.
|
|
7
|
-
|
|
8
|
-
import { fileURLToPath } from 'node:url';
|
|
9
|
-
|
|
10
|
-
import starlight from '@astrojs/starlight';
|
|
11
|
-
|
|
12
|
-
import { resolveOptions } from './lib/options.mjs';
|
|
13
|
-
import { buildSidebar } from './lib/sidebar.mjs';
|
|
14
|
-
|
|
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
|
-
* @type {Record<import('./index').ViewName, [pattern: string, file: string][]>}
|
|
19
|
-
*/
|
|
20
|
-
const VIEW_ROUTES = {
|
|
21
|
-
now: [['/plan/now', 'plan/now.astro']],
|
|
22
|
-
milestones: [
|
|
23
|
-
['/plan/milestones', 'plan/milestones/index.astro'],
|
|
24
|
-
['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
|
|
25
|
-
],
|
|
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
|
-
};
|
|
34
|
-
|
|
35
|
-
const NO_EXTERNAL = ['@astrojs/starlight', '@purview-dev/pm-docs-site'];
|
|
36
|
-
const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
|
|
37
|
-
|
|
38
|
-
const VIRTUAL_ID = 'virtual:pm-docs-site/config';
|
|
39
|
-
const RESOLVED_ID = `\0${VIRTUAL_ID}`;
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* @param {import('./index').PmDocsSiteOptions} options
|
|
43
|
-
* @returns {import('astro').AstroIntegration & { pmDocsSiteOptions: import('./index').PmDocsSiteOptions }}
|
|
44
|
-
*/
|
|
45
|
-
export default function pmDocsSite(options) {
|
|
46
|
-
return {
|
|
47
|
-
name: 'pm-docs-site',
|
|
48
|
-
pmDocsSiteOptions: options,
|
|
49
|
-
hooks: {
|
|
50
|
-
'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
|
|
51
|
-
const resolved = resolveOptions(options, fileURLToPath(config.root));
|
|
52
|
-
|
|
53
|
-
for (const [view, routes] of Object.entries(VIEW_ROUTES)) {
|
|
54
|
-
if (!resolved.views[/** @type {import('./index').ViewName} */ (view)]) continue;
|
|
55
|
-
|
|
56
|
-
for (const [pattern, file] of routes) {
|
|
57
|
-
injectRoute({ pattern, entrypoint: new URL(`./src/routes/${file}`, import.meta.url) });
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
updateConfig({
|
|
62
|
-
srcDir: new URL('./src/', import.meta.url),
|
|
63
|
-
integrations: [
|
|
64
|
-
starlight({
|
|
65
|
-
title: resolved.title,
|
|
66
|
-
...(resolved.description ? { description: resolved.description } : {}),
|
|
67
|
-
sidebar: buildSidebar(resolved),
|
|
68
|
-
// Every page uses the full width (src/styles/width.css).
|
|
69
|
-
customCss: [fileURLToPath(new URL('./src/styles/width.css', import.meta.url))],
|
|
70
|
-
}),
|
|
71
|
-
],
|
|
72
|
-
vite: {
|
|
73
|
-
plugins: [
|
|
74
|
-
{
|
|
75
|
-
name: 'pm-docs-site:config',
|
|
76
|
-
/** @param {string} id */
|
|
77
|
-
resolveId: (id) => (id === VIRTUAL_ID ? RESOLVED_ID : undefined),
|
|
78
|
-
/** @param {string} id */
|
|
79
|
-
load: (id) => (id === RESOLVED_ID ? `export default ${JSON.stringify(resolved)};` : undefined),
|
|
80
|
-
},
|
|
81
|
-
{
|
|
82
|
-
// Bundle Starlight and this package in every server environment, whatever
|
|
83
|
-
// the consumer's package.json lists: externalised, Starlight cannot import
|
|
84
|
-
// astro:middleware. Astro 7 renders static pages in its own `prerender`
|
|
85
|
-
// environment, which top-level `vite.ssr` does not reach.
|
|
86
|
-
name: 'pm-docs-site:no-external',
|
|
87
|
-
/** @param {string} name */
|
|
88
|
-
configEnvironment: (name) =>
|
|
89
|
-
SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
|
|
90
|
-
},
|
|
91
|
-
],
|
|
92
|
-
},
|
|
93
|
-
});
|
|
94
|
-
},
|
|
95
|
-
},
|
|
96
|
-
};
|
|
97
|
-
}
|
package/lib/options.mjs
DELETED
|
@@ -1,67 +0,0 @@
|
|
|
1
|
-
// @ts-check
|
|
2
|
-
// The integration's options: defaults, validation, and paths made absolute from
|
|
3
|
-
// the site root, so the pages and the content config never resolve a path again.
|
|
4
|
-
|
|
5
|
-
import { resolve } from 'node:path';
|
|
6
|
-
|
|
7
|
-
/** @typedef {import('../index').PmDocsSiteOptions} PmDocsSiteOptions */
|
|
8
|
-
/** @typedef {import('../index').ResolvedOptions} ResolvedOptions */
|
|
9
|
-
/** @typedef {import('../index').ViewName} ViewName */
|
|
10
|
-
|
|
11
|
-
/** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
|
|
12
|
-
export const VIEW_NAMES = /** @type {const} */ (['now', 'milestones', 'features', 'inbox', 'briefs', 'strategy']);
|
|
13
|
-
|
|
14
|
-
/** Where the export lives by default, relative to the site root. */
|
|
15
|
-
const DEFAULT_PLANNING = '../planning/planning.json';
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
* Throw a pm-docs-site message for a malformed `docs` option, which a plain
|
|
19
|
-
* astro.config.mjs does not type-check.
|
|
20
|
-
* @param {unknown} docs
|
|
21
|
-
*/
|
|
22
|
-
function checkDocs(docs) {
|
|
23
|
-
const value = /** @type {{ root?: unknown; sources?: unknown }} */ (docs ?? {});
|
|
24
|
-
|
|
25
|
-
if (typeof value.root !== 'string') throw new Error('pm-docs-site: docs.root must be a path');
|
|
26
|
-
if (!Array.isArray(value.sources)) throw new Error('pm-docs-site: docs.sources must be a list of sources');
|
|
27
|
-
|
|
28
|
-
for (const source of value.sources) {
|
|
29
|
-
if (typeof source?.base !== 'string' || !Array.isArray(source?.include)) {
|
|
30
|
-
throw new Error(`pm-docs-site: docs source "${String(source?.label)}" needs base and include`);
|
|
31
|
-
}
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
/**
|
|
36
|
-
* @param {PmDocsSiteOptions} options
|
|
37
|
-
* @param {string} root the site root, absolute
|
|
38
|
-
* @returns {ResolvedOptions}
|
|
39
|
-
*/
|
|
40
|
-
export function resolveOptions(options, root) {
|
|
41
|
-
if (!options || typeof options.title !== 'string' || options.title === '') {
|
|
42
|
-
throw new Error('pm-docs-site: title is required');
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
const listed = options.views ?? VIEW_NAMES;
|
|
46
|
-
|
|
47
|
-
for (const name of listed) {
|
|
48
|
-
if (!VIEW_NAMES.includes(name)) {
|
|
49
|
-
throw new Error(`pm-docs-site: unknown view "${name}"; expected one of ${VIEW_NAMES.join(', ')}`);
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
if (options.docs !== undefined) checkDocs(options.docs);
|
|
54
|
-
|
|
55
|
-
const views = /** @type {Record<ViewName, boolean>} */ (
|
|
56
|
-
Object.fromEntries(VIEW_NAMES.map((name) => [name, listed.includes(name)]))
|
|
57
|
-
);
|
|
58
|
-
|
|
59
|
-
return {
|
|
60
|
-
title: options.title,
|
|
61
|
-
description: options.description ?? null,
|
|
62
|
-
planning: resolve(root, options.planning ?? DEFAULT_PLANNING),
|
|
63
|
-
planningLabel: (options.planning ?? DEFAULT_PLANNING).replace(/\\/g, '/'),
|
|
64
|
-
docs: options.docs ? { root: resolve(root, options.docs.root), sources: options.docs.sources } : null,
|
|
65
|
-
views,
|
|
66
|
-
};
|
|
67
|
-
}
|
package/lib/schema-version.mjs
DELETED
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
// @ts-check
|
|
2
|
-
// The pm-export schemaVersions this package reads, declared once. A new export
|
|
3
|
-
// format is supported by adding its version here, with the page changes it needs.
|
|
4
|
-
|
|
5
|
-
/** @type {readonly number[]} */
|
|
6
|
-
export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([3]);
|
|
7
|
-
|
|
8
|
-
/** The plan export is missing, unreadable, or in a format this package does not read. */
|
|
9
|
-
export class PlanningExportError extends Error {
|
|
10
|
-
/** @param {string} message */
|
|
11
|
-
constructor(message) {
|
|
12
|
-
super(`${message} Run the pm-export skill to write planning.json.`);
|
|
13
|
-
this.name = 'PlanningExportError';
|
|
14
|
-
}
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
* Throw unless the export's schemaVersion is one this package reads.
|
|
19
|
-
* @param {unknown} version
|
|
20
|
-
* @param {string} path the export's path, for the message
|
|
21
|
-
* @returns {void}
|
|
22
|
-
*/
|
|
23
|
-
export function checkSchemaVersion(version, path) {
|
|
24
|
-
if (typeof version === 'number' && SUPPORTED_SCHEMA_VERSIONS.includes(version)) return;
|
|
25
|
-
|
|
26
|
-
throw new PlanningExportError(
|
|
27
|
-
`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`,
|
|
28
|
-
);
|
|
29
|
-
}
|
package/lib/sidebar.mjs
DELETED
|
@@ -1,47 +0,0 @@
|
|
|
1
|
-
// @ts-check
|
|
2
|
-
// The Starlight sidebar: the plan, its optional views switched on in the
|
|
3
|
-
// options, then one group per docs source that has pages.
|
|
4
|
-
|
|
5
|
-
import { pagesOf } from './repo-docs.mjs';
|
|
6
|
-
|
|
7
|
-
/** @typedef {import('../index').ResolvedOptions} ResolvedOptions */
|
|
8
|
-
/**
|
|
9
|
-
* @typedef {string | { label: string; link: string } | { label: string; items: SidebarItem[]; collapsed?: boolean }} SidebarItem
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
/**
|
|
13
|
-
* @param {ResolvedOptions} options
|
|
14
|
-
* @returns {SidebarItem[]}
|
|
15
|
-
*/
|
|
16
|
-
export function buildSidebar(options) {
|
|
17
|
-
const { views, docs } = options;
|
|
18
|
-
|
|
19
|
-
/** @type {(SidebarItem | false)[]} */
|
|
20
|
-
const plan = [
|
|
21
|
-
views.now && { label: 'Now', link: '/plan/now/' },
|
|
22
|
-
{ label: 'Board', link: '/plan/board/' },
|
|
23
|
-
{ label: 'Roadmap', link: '/plan/roadmap/' },
|
|
24
|
-
views.milestones && { label: 'Milestones', link: '/plan/milestones/' },
|
|
25
|
-
views.features && { label: 'Features', link: '/plan/features/' },
|
|
26
|
-
{ label: 'Log', link: '/plan/log/' },
|
|
27
|
-
{ label: 'Risks', link: '/plan/risks/' },
|
|
28
|
-
views.inbox && { label: 'Inbox', link: '/plan/inbox/' },
|
|
29
|
-
views.briefs && { label: 'Briefs', link: '/plan/briefs/' },
|
|
30
|
-
views.strategy && { label: 'Strategy', link: '/plan/strategy/' },
|
|
31
|
-
];
|
|
32
|
-
|
|
33
|
-
/** @type {SidebarItem[]} */
|
|
34
|
-
const groups = docs
|
|
35
|
-
? docs.sources
|
|
36
|
-
.filter((source) => !source.hidden)
|
|
37
|
-
.map((source) => ({
|
|
38
|
-
label: source.label,
|
|
39
|
-
collapsed: source.collapsed ?? false,
|
|
40
|
-
items: pagesOf(source, docs.root).map((page) => page.id),
|
|
41
|
-
}))
|
|
42
|
-
// Starlight rejects an empty group.
|
|
43
|
-
.filter((group) => group.items.length > 0)
|
|
44
|
-
: [];
|
|
45
|
-
|
|
46
|
-
return [{ label: 'Plan', items: plan.filter((item) => item !== false) }, ...groups];
|
|
47
|
-
}
|
package/lib/site-options.mjs
DELETED
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
// @ts-check
|
|
2
|
-
// The options a site gives the integration, read the way the CLI needs them:
|
|
3
|
-
// from its astro.config file when it has one, else from command-line flags.
|
|
4
|
-
|
|
5
|
-
import { existsSync } from 'node:fs';
|
|
6
|
-
import { join } from 'node:path';
|
|
7
|
-
import { pathToFileURL } from 'node:url';
|
|
8
|
-
|
|
9
|
-
/** @typedef {import('../index').PmDocsSiteOptions} PmDocsSiteOptions */
|
|
10
|
-
|
|
11
|
-
const CONFIG_FILES = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts'];
|
|
12
|
-
|
|
13
|
-
/**
|
|
14
|
-
* @param {string} siteDir absolute
|
|
15
|
-
* @param {{ title?: string; planning?: string }} flags
|
|
16
|
-
* @returns {Promise<{ options: PmDocsSiteOptions; configFile: string | null }>}
|
|
17
|
-
*/
|
|
18
|
-
export async function loadSiteOptions(siteDir, flags) {
|
|
19
|
-
const configFile = CONFIG_FILES.map((name) => join(siteDir, name)).find((file) => existsSync(file)) ?? null;
|
|
20
|
-
|
|
21
|
-
if (!configFile) {
|
|
22
|
-
return {
|
|
23
|
-
options: { title: flags.title ?? 'Project plan', ...(flags.planning ? { planning: flags.planning } : {}) },
|
|
24
|
-
configFile: null,
|
|
25
|
-
};
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
const config = (await import(pathToFileURL(configFile).href)).default ?? {};
|
|
29
|
-
/** @type {unknown[]} */
|
|
30
|
-
const integrations = (Array.isArray(config.integrations) ? config.integrations : []).flat(Infinity);
|
|
31
|
-
const ours = /** @type {{ pmDocsSiteOptions?: PmDocsSiteOptions } | undefined} */ (
|
|
32
|
-
integrations.find((entry) => /** @type {{ name?: string } | null} */ (entry)?.name === 'pm-docs-site')
|
|
33
|
-
);
|
|
34
|
-
|
|
35
|
-
if (!ours?.pmDocsSiteOptions) throw new Error(`pm-docs-site: no pm-docs-site integration in ${configFile}`);
|
|
36
|
-
|
|
37
|
-
return { options: ours.pmDocsSiteOptions, configFile };
|
|
38
|
-
}
|