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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +63 -11
  2. package/dist/cli.d.ts +2 -0
  3. package/dist/cli.js +90 -0
  4. package/dist/index.d.ts +7 -0
  5. package/dist/index.js +118 -0
  6. package/dist/options.d.ts +5 -0
  7. package/dist/options.js +46 -0
  8. package/dist/repo-docs.d.ts +33 -0
  9. package/dist/repo-docs.js +94 -0
  10. package/dist/schema-version.d.ts +10 -0
  11. package/dist/schema-version.js +19 -0
  12. package/dist/sidebar.d.ts +10 -0
  13. package/dist/sidebar.js +30 -0
  14. package/dist/site-options.d.ts +9 -0
  15. package/dist/site-options.js +39 -0
  16. package/dist/types.d.ts +47 -0
  17. package/dist/types.js +4 -0
  18. package/lib/{repo-docs.mjs → repo-docs.ts} +22 -46
  19. package/lib/{schema-version.mjs → schema-version.ts} +4 -9
  20. package/package.json +14 -8
  21. package/src/components/PlanInteractions.astro +15 -3
  22. package/src/components/board/Board.tsx +244 -0
  23. package/src/components/board/KanbanItemCard.tsx +129 -0
  24. package/src/components/board/LinkRuns.tsx +21 -0
  25. package/src/components/board/TaskKanbanCard.tsx +81 -0
  26. package/src/components/board/useBoardUrlState.ts +41 -0
  27. package/src/components/timeline/Timeline.tsx +159 -0
  28. package/src/components/timeline/useTimelineLayout.ts +39 -0
  29. package/src/env.d.ts +2 -2
  30. package/src/lib/board-data.ts +84 -0
  31. package/src/lib/board.ts +209 -0
  32. package/src/lib/planning.ts +66 -38
  33. package/src/lib/references.ts +1 -1
  34. package/src/lib/timeline.ts +156 -0
  35. package/src/loaders/repo-docs.ts +3 -3
  36. package/src/pages/plan/board.astro +14 -113
  37. package/src/pages/plan/roadmap.astro +20 -2
  38. package/src/scripts/plan.ts +3 -49
  39. package/src/styles/components.css +127 -10
  40. package/src/styles/kanban.css +277 -0
  41. package/src/styles/timeline.css +210 -0
  42. package/cli.mjs +0 -120
  43. package/index.d.ts +0 -49
  44. package/index.mjs +0 -97
  45. package/lib/options.mjs +0 -67
  46. package/lib/sidebar.mjs +0 -47
  47. package/lib/site-options.mjs +0 -38
package/README.md CHANGED
@@ -8,13 +8,14 @@ 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
- Unpublished: version `0.1.0-pre.1` and `private` until roadmap item R-013 publishes
12
- it to npm. Until then the repository's `docs-site/` still renders the
13
- `pm-docs-site` skill's templates.
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.mjs`. No `src/`
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
 
20
21
  ```json
@@ -32,7 +33,7 @@ folder: the integration points Astro's `srcDir` at the package.
32
33
  ```
33
34
 
34
35
  ```js
35
- // astro.config.mjs
36
+ // astro.config.ts
36
37
  import pmDocsSite from '@purview-dev/pm-docs-site';
37
38
 
38
39
  export default {
@@ -61,11 +62,61 @@ export default {
61
62
 
62
63
  Home, Board, Roadmap, Log and Risks are always rendered. A docs source has
63
64
  `label`, `base`, `include`, and optionally `prefix`, `indexFile`, `order`,
64
- `collapsed`, and `hidden` (see `index.d.ts`).
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%.
65
116
 
66
117
  ## CLI
67
118
 
68
- The CLI runs under Node 22 or later.
119
+ The CLI runs under Node 24 or later.
69
120
 
70
121
  - `pm-docs-site build [site-dir]` and `pm-docs-site dev [site-dir]` run Astro
71
122
  on the site. A site with no `astro.config.*` builds from
@@ -76,7 +127,7 @@ The CLI runs under Node 22 or later.
76
127
 
77
128
  ## Supported exports
78
129
 
79
- `SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.mjs`: pm-export
130
+ `SUPPORTED_SCHEMA_VERSIONS` in `lib/schema-version.ts`: pm-export
80
131
  `schemaVersion` 3. Any other version fails the build and `check`, and the
81
132
  message says to run the `pm-export` skill.
82
133
 
@@ -123,9 +174,10 @@ the purview-dev release rules:
123
174
  | REL003 | a stable version runs from `main` | fails |
124
175
 
125
176
  While `package.json` sets `"private": true` it also skips, green. Then it
126
- installs, tests, type-checks, and runs `scripts/check-exports.mjs`, which is
127
- also the `prepublishOnly` script, so a local `npm publish` cannot burn a
128
- version on a package with missing files. It publishes a prerelease
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
129
181
  (`0.1.0-pre.1`) under the `prerelease` dist-tag and a stable version under
130
182
  `latest`, skips a version already on the registry, and keeps `latest` on the
131
183
  newest prerelease until a stable release exists. Only then does it create the
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,90 @@
1
+ #!/usr/bin/env node
2
+ // pm-docs-site <dev | build | check> [site-dir] [--title <t>] [--planning <p>]
3
+ //
4
+ // dev and build run Astro on the site folder: with its astro.config file when it
5
+ // has one, else with the integration built from --title and --planning. check
6
+ // builds nothing: it reads the export and the docs sources and reports problems.
7
+ import { existsSync, readFileSync } from 'node:fs';
8
+ import { resolve } from 'node:path';
9
+ import { resolveOptions } from "./options.js";
10
+ import { checkSchemaVersion } from "./schema-version.js";
11
+ import { loadSiteOptions } from "./site-options.js";
12
+ const USAGE = 'usage: pm-docs-site <dev | build | check> [site-dir] [--title <title>] [--planning <path>]';
13
+ function parse(argv) {
14
+ const flags = {};
15
+ const positional = [];
16
+ for (let index = 0; index < argv.length; index++) {
17
+ const arg = argv[index];
18
+ if (arg === '--title' || arg === '--planning') {
19
+ const value = argv[++index];
20
+ if (value === undefined)
21
+ throw new Error(`pm-docs-site: ${arg} needs a value`);
22
+ flags[arg === '--title' ? 'title' : 'planning'] = value;
23
+ }
24
+ else {
25
+ positional.push(arg);
26
+ }
27
+ }
28
+ return { command: positional[0], siteDir: resolve(positional[1] ?? process.cwd()), flags };
29
+ }
30
+ /** The problems check finds, one line each. */
31
+ function problems(options) {
32
+ const found = [];
33
+ if (!existsSync(options.planning)) {
34
+ found.push(`No plan export at ${options.planning}. Run the pm-export skill to write planning.json.`);
35
+ }
36
+ else {
37
+ try {
38
+ const planning = JSON.parse(readFileSync(options.planning, 'utf8'));
39
+ checkSchemaVersion(planning.schemaVersion, options.planning);
40
+ }
41
+ catch (error) {
42
+ found.push(error.message);
43
+ }
44
+ }
45
+ for (const source of options.docs?.sources ?? []) {
46
+ const base = resolve(options.docs?.root ?? '.', source.base);
47
+ if (!existsSync(base))
48
+ found.push(`docs source "${source.label}": no folder at ${base}`);
49
+ }
50
+ return found;
51
+ }
52
+ async function main() {
53
+ const { command, siteDir, flags } = parse(process.argv.slice(2));
54
+ if (command !== 'dev' && command !== 'build' && command !== 'check') {
55
+ console.error(USAGE);
56
+ return 2;
57
+ }
58
+ const { options, configFile } = await loadSiteOptions(siteDir, flags);
59
+ if (command === 'check') {
60
+ const resolved = resolveOptions(options, siteDir);
61
+ const found = problems(resolved);
62
+ for (const line of found)
63
+ console.error(`pm-docs-site: ${line}`);
64
+ if (found.length)
65
+ return 1;
66
+ const { schemaVersion } = JSON.parse(readFileSync(resolved.planning, 'utf8'));
67
+ console.log(`pm-docs-site: ok (${resolved.planning}, schemaVersion ${schemaVersion})`);
68
+ return 0;
69
+ }
70
+ const astro = await import('astro');
71
+ const inline = { root: siteDir };
72
+ if (!configFile) {
73
+ const { default: pmDocsSite } = await import("./index.js");
74
+ Object.assign(inline, { configFile: false, integrations: [pmDocsSite(options)] });
75
+ }
76
+ if (command === 'build') {
77
+ await astro.build(inline);
78
+ return 0;
79
+ }
80
+ await astro.dev(inline);
81
+ // The dev server keeps the process alive until it is stopped.
82
+ return null;
83
+ }
84
+ main().then((code) => {
85
+ if (code !== null)
86
+ process.exitCode = code;
87
+ }, (error) => {
88
+ console.error(error instanceof Error ? error.message : error);
89
+ process.exitCode = 1;
90
+ });
@@ -0,0 +1,7 @@
1
+ import type { AstroIntegration } from 'astro';
2
+ import type { PmDocsSiteOptions } from './types.js';
3
+ export type * from './types.js';
4
+ /** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
5
+ export default function pmDocsSite(options: PmDocsSiteOptions): AstroIntegration & {
6
+ pmDocsSiteOptions: PmDocsSiteOptions;
7
+ };
package/dist/index.js ADDED
@@ -0,0 +1,118 @@
1
+ // The pm-docs-site Astro integration. The consumer's astro.config.ts holds
2
+ // only `integrations: [pmDocsSite({ title, ... })]`: this points Astro's srcDir
3
+ // at the package's own src/ (pages, components, content config), adds
4
+ // Starlight with the plan sidebar, adds React so pages can render `.tsx` islands with
5
+ // no consumer config, and serves the resolved options to the pages as
6
+ // `virtual:pm-docs-site/config`.
7
+ import { existsSync } from 'node:fs';
8
+ import { dirname, join, resolve } from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+ import react from '@astrojs/react';
11
+ import starlight from '@astrojs/starlight';
12
+ import { resolveOptions } from "./options.js";
13
+ import { buildSidebar } from "./sidebar.js";
14
+ /**
15
+ * The pages each optional view owns, in src/routes/ so Astro routes them only
16
+ * when the view is on. Home, Board, Roadmap, Log and Risks are in src/pages/.
17
+ */
18
+ const VIEW_ROUTES = {
19
+ now: [['/plan/now', 'plan/now.astro']],
20
+ milestones: [
21
+ ['/plan/milestones', 'plan/milestones/index.astro'],
22
+ ['/plan/milestones/[milestone]', 'plan/milestones/[milestone].astro'],
23
+ ],
24
+ features: [
25
+ ['/plan/features', 'plan/features/index.astro'],
26
+ ['/plan/features/[id]', 'plan/features/[id].astro'],
27
+ ],
28
+ inbox: [['/plan/inbox', 'plan/inbox.astro']],
29
+ briefs: [['/plan/briefs', 'plan/briefs.astro']],
30
+ strategy: [['/plan/strategy', 'plan/strategy.astro']],
31
+ };
32
+ const PACKAGE_NAME = '@purview-dev/pm-docs-site';
33
+ const REACT_INTEGRATION = '@astrojs/react';
34
+ const NO_EXTERNAL = ['@astrojs/starlight', PACKAGE_NAME];
35
+ const SERVER_ENVIRONMENTS = ['ssr', 'astro', 'prerender'];
36
+ /**
37
+ * Whether `name` is installed in a node_modules folder at or above `root`,
38
+ * walked as Vite resolves it: under Bun, `createRequire` also finds Bun's
39
+ * global cache, which Vite never looks in.
40
+ */
41
+ function resolvesFrom(name, root) {
42
+ for (let dir = resolve(root);; dir = dirname(dir)) {
43
+ if (existsSync(join(dir, 'node_modules', name, 'package.json')))
44
+ return true;
45
+ if (dirname(dir) === dir)
46
+ return false;
47
+ }
48
+ }
49
+ /**
50
+ * The `optimizeDeps.include` entries the site lacks. The island's renderer
51
+ * (@astrojs/react-renderer) imports react-dom/client from under node_modules,
52
+ * which Vite's dev optimizer skips, so React's CommonJS reaches the browser
53
+ * raw and the Board never hydrates. An installed package is pre-bundled
54
+ * through itself (`<package> > react-dom/client`); a site that cannot resolve
55
+ * the package by name (this repository's fixtures) names react-dom/client
56
+ * plainly, since naming a package Vite cannot resolve breaks the optimizer.
57
+ * Only missing entries: Vite's mergeConfig concatenates arrays.
58
+ */
59
+ function optimizedDependencies(include, root) {
60
+ const existing = Array.isArray(include) ? include : [];
61
+ const entry = resolvesFrom(PACKAGE_NAME, root) ? `${PACKAGE_NAME} > react-dom/client` : 'react-dom/client';
62
+ return existing.includes(entry) ? [] : [entry];
63
+ }
64
+ const VIRTUAL_ID = 'virtual:pm-docs-site/config';
65
+ const RESOLVED_ID = `\0${VIRTUAL_ID}`;
66
+ /** The pm-docs-site integration: the plan pages, Starlight, and the docs collection. */
67
+ export default function pmDocsSite(options) {
68
+ return {
69
+ name: 'pm-docs-site',
70
+ pmDocsSiteOptions: options,
71
+ hooks: {
72
+ 'astro:config:setup': ({ config, updateConfig, injectRoute }) => {
73
+ const root = fileURLToPath(config.root);
74
+ const resolved = resolveOptions(options, root);
75
+ // A consumer that adds React itself keeps its own: two would register the renderer twice.
76
+ const hasReact = (config.integrations ?? []).some((integration) => integration.name === REACT_INTEGRATION);
77
+ for (const [view, routes] of Object.entries(VIEW_ROUTES)) {
78
+ if (!resolved.views[view])
79
+ continue;
80
+ for (const [pattern, file] of routes) {
81
+ injectRoute({ pattern, entrypoint: new URL(`../src/routes/${file}`, import.meta.url) });
82
+ }
83
+ }
84
+ updateConfig({
85
+ srcDir: new URL('../src/', import.meta.url),
86
+ integrations: [
87
+ starlight({
88
+ title: resolved.title,
89
+ ...(resolved.description ? { description: resolved.description } : {}),
90
+ sidebar: buildSidebar(resolved),
91
+ // Every page uses the full width (src/styles/width.css).
92
+ customCss: [fileURLToPath(new URL('../src/styles/width.css', import.meta.url))],
93
+ }),
94
+ ...(hasReact ? [] : [react()]),
95
+ ],
96
+ vite: {
97
+ optimizeDeps: { include: optimizedDependencies(config.vite?.optimizeDeps?.include, root) },
98
+ plugins: [
99
+ {
100
+ name: 'pm-docs-site:config',
101
+ resolveId: (id) => (id === VIRTUAL_ID ? RESOLVED_ID : undefined),
102
+ load: (id) => (id === RESOLVED_ID ? `export default ${JSON.stringify(resolved)};` : undefined),
103
+ },
104
+ {
105
+ // Bundle Starlight and this package in every server environment, whatever
106
+ // the consumer's package.json lists: externalised, Starlight cannot import
107
+ // astro:middleware. Astro 7 renders static pages in its own `prerender`
108
+ // environment, which top-level `vite.ssr` does not reach.
109
+ name: 'pm-docs-site:no-external',
110
+ configEnvironment: (name) => SERVER_ENVIRONMENTS.includes(name) ? { resolve: { noExternal: [...NO_EXTERNAL] } } : undefined,
111
+ },
112
+ ],
113
+ },
114
+ });
115
+ },
116
+ },
117
+ };
118
+ }
@@ -0,0 +1,5 @@
1
+ import type { PmDocsSiteOptions, ResolvedOptions, ViewName } from './types.js';
2
+ /** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
3
+ export declare const VIEW_NAMES: readonly ViewName[];
4
+ /** @param root the site root, absolute */
5
+ export declare function resolveOptions(options: PmDocsSiteOptions, root: string): ResolvedOptions;
@@ -0,0 +1,46 @@
1
+ // The integration's options: defaults, validation, and paths made absolute from
2
+ // the site root, so the pages and the content config never resolve a path again.
3
+ import { resolve } from 'node:path';
4
+ /** The optional plan views. Home, Board, Roadmap, Log and Risks are always on. */
5
+ export const VIEW_NAMES = ['now', 'milestones', 'features', 'inbox', 'briefs', 'strategy'];
6
+ /** Where the export lives by default, relative to the site root. */
7
+ const DEFAULT_PLANNING = '../planning/planning.json';
8
+ /**
9
+ * Throw a pm-docs-site message for a malformed `docs` option, which a plain
10
+ * JavaScript astro.config does not type-check.
11
+ */
12
+ function checkDocs(docs) {
13
+ const value = (docs ?? {});
14
+ if (typeof value.root !== 'string')
15
+ throw new Error('pm-docs-site: docs.root must be a path');
16
+ if (!Array.isArray(value.sources))
17
+ throw new Error('pm-docs-site: docs.sources must be a list of sources');
18
+ for (const source of value.sources) {
19
+ if (typeof source?.base !== 'string' || !Array.isArray(source?.include)) {
20
+ throw new Error(`pm-docs-site: docs source "${String(source?.label)}" needs base and include`);
21
+ }
22
+ }
23
+ }
24
+ /** @param root the site root, absolute */
25
+ export function resolveOptions(options, root) {
26
+ if (!options || typeof options.title !== 'string' || options.title === '') {
27
+ throw new Error('pm-docs-site: title is required');
28
+ }
29
+ const listed = options.views ?? VIEW_NAMES;
30
+ for (const name of listed) {
31
+ if (!VIEW_NAMES.includes(name)) {
32
+ throw new Error(`pm-docs-site: unknown view "${name}"; expected one of ${VIEW_NAMES.join(', ')}`);
33
+ }
34
+ }
35
+ if (options.docs !== undefined)
36
+ checkDocs(options.docs);
37
+ const views = Object.fromEntries(VIEW_NAMES.map((name) => [name, listed.includes(name)]));
38
+ return {
39
+ title: options.title,
40
+ description: options.description ?? null,
41
+ planning: resolve(root, options.planning ?? DEFAULT_PLANNING),
42
+ planningLabel: (options.planning ?? DEFAULT_PLANNING).replace(/\\/g, '/'),
43
+ docs: options.docs ? { root: resolve(root, options.docs.root), sources: options.docs.sources } : null,
44
+ views,
45
+ };
46
+ }
@@ -0,0 +1,33 @@
1
+ import type { DocsSource } from './types.js';
2
+ export interface DocsPage {
3
+ id: string;
4
+ file: string;
5
+ }
6
+ /** A glob as a regular expression over `/`-separated paths. */
7
+ export declare function globToRegExp(glob: string): RegExp;
8
+ /** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
9
+ export declare function pageId(source: DocsSource, path: string): string;
10
+ /** Every file a source matches, as page IDs in its sidebar order. */
11
+ export declare function pagesOf(source: DocsSource, repoRoot: string): DocsPage[];
12
+ /** Simple `key: value` frontmatter (one line per key) and the body after it. */
13
+ export declare function splitFrontmatter(markdown: string): {
14
+ data: Record<string, string>;
15
+ body: string;
16
+ };
17
+ /**
18
+ * The page title and the body without it.
19
+ *
20
+ * The title is the first `# ` heading when nothing but blank lines and HTML
21
+ * comments come before it; otherwise the fallback is the title and the body is
22
+ * kept whole.
23
+ */
24
+ export declare function splitTitle(markdown: string, fallback: string): {
25
+ title: string;
26
+ body: string;
27
+ };
28
+ /** Title, description, and body for one page. */
29
+ export declare function readPage(markdown: string, file: string): {
30
+ title: string;
31
+ description?: string;
32
+ body: string;
33
+ };
@@ -0,0 +1,94 @@
1
+ // Repository Markdown as pages: which files a docs source matches, their page
2
+ // IDs, and each page's title and body. Node-loadable (no Astro or Vite import)
3
+ // because the sidebar is built from it while astro.config loads; the Astro
4
+ // loader in src/loaders/repo-docs.ts uses the same functions.
5
+ //
6
+ // Starlight requires a `title` in every page's frontmatter; repository Markdown
7
+ // rarely has one. The title is frontmatter `title`, else the first `# Title`
8
+ // heading (dropped from the body, so it is not shown twice), else frontmatter
9
+ // `name`, else the file name, so the files stay exactly as their authors write them.
10
+ import { existsSync, readdirSync } from 'node:fs';
11
+ import { basename, dirname, join, resolve, sep } from 'node:path';
12
+ /** A glob as a regular expression over `/`-separated paths. */
13
+ export function globToRegExp(glob) {
14
+ const pattern = glob
15
+ .split(/(\*\*\/|\*\*|\*)/)
16
+ .map((part) => part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
17
+ .join('');
18
+ return new RegExp(`^${pattern}$`, 'i');
19
+ }
20
+ /** The page ID (and URL path) for a file: prefix, path without `.md`, lower case. */
21
+ export function pageId(source, path) {
22
+ let page = path.replace(/\.md$/i, '');
23
+ if (source.indexFile && basename(path).toLowerCase() === source.indexFile.toLowerCase()) {
24
+ page = dirname(path) === '.' ? 'index' : dirname(path);
25
+ }
26
+ return `${source.prefix ?? ''}${page}`.toLowerCase();
27
+ }
28
+ /** Every file a source matches, as page IDs in its sidebar order. */
29
+ export function pagesOf(source, repoRoot) {
30
+ const base = resolve(repoRoot, source.base);
31
+ if (!existsSync(base))
32
+ return [];
33
+ const patterns = source.include.map(globToRegExp);
34
+ const pages = readdirSync(base, { recursive: true })
35
+ .map((file) => file.split(sep).join('/'))
36
+ .filter((file) => !file.split('/').includes('node_modules') && patterns.some((pattern) => pattern.test(file)))
37
+ .map((file) => ({ id: pageId(source, file), file: join(base, file) }))
38
+ .sort((a, b) => a.id.localeCompare(b.id));
39
+ return source.order === 'desc' ? pages.reverse() : pages;
40
+ }
41
+ /** Simple `key: value` frontmatter (one line per key) and the body after it. */
42
+ export function splitFrontmatter(markdown) {
43
+ const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
44
+ if (!match)
45
+ return { data: {}, body: markdown };
46
+ const data = {};
47
+ for (const line of (match[1] ?? '').split('\n')) {
48
+ const pair = /^([\w-]+):\s*(.*?)\s*$/.exec(line);
49
+ if (pair && pair[1] && pair[2])
50
+ data[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
51
+ }
52
+ return { data, body: markdown.slice(match[0].length) };
53
+ }
54
+ /**
55
+ * The page title and the body without it.
56
+ *
57
+ * The title is the first `# ` heading when nothing but blank lines and HTML
58
+ * comments come before it; otherwise the fallback is the title and the body is
59
+ * kept whole.
60
+ */
61
+ export function splitTitle(markdown, fallback) {
62
+ const lines = markdown.split('\n');
63
+ let index = 0;
64
+ let inComment = false;
65
+ for (; index < lines.length; index++) {
66
+ const line = (lines[index] ?? '').trim();
67
+ if (inComment) {
68
+ if (line.includes('-->'))
69
+ inComment = false;
70
+ continue;
71
+ }
72
+ if (line === '')
73
+ continue;
74
+ if (line.startsWith('<!--')) {
75
+ inComment = !line.includes('-->');
76
+ continue;
77
+ }
78
+ break;
79
+ }
80
+ const heading = /^#\s+(.+?)\s*#*\s*$/.exec(lines[index] ?? '');
81
+ if (!heading || !heading[1])
82
+ return { title: fallback, body: markdown };
83
+ let start = index + 1;
84
+ while (start < lines.length && (lines[start] ?? '').trim() === '')
85
+ start++;
86
+ return { title: heading[1], body: lines.slice(start).join('\n') };
87
+ }
88
+ /** Title, description, and body for one page. */
89
+ export function readPage(markdown, file) {
90
+ const { data, body } = splitFrontmatter(markdown);
91
+ const fallback = data.name ?? basename(file, '.md');
92
+ const split = data.title ? { title: data.title, body } : splitTitle(body, fallback);
93
+ return { title: split.title, ...(data.description ? { description: data.description } : {}), body: split.body };
94
+ }
@@ -0,0 +1,10 @@
1
+ export declare const SUPPORTED_SCHEMA_VERSIONS: readonly number[];
2
+ /** The plan export is missing, unreadable, or in a format this package does not read. */
3
+ export declare class PlanningExportError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ /**
7
+ * Throw unless the export's schemaVersion is one this package reads.
8
+ * @param path the export's path, for the message
9
+ */
10
+ export declare function checkSchemaVersion(version: unknown, path: string): void;
@@ -0,0 +1,19 @@
1
+ // The pm-export schemaVersions this package reads, declared once. A new export
2
+ // format is supported by adding its version here, with the page changes it needs.
3
+ export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([3]);
4
+ /** The plan export is missing, unreadable, or in a format this package does not read. */
5
+ export class PlanningExportError extends Error {
6
+ constructor(message) {
7
+ super(`${message} Run the pm-export skill to write planning.json.`);
8
+ this.name = 'PlanningExportError';
9
+ }
10
+ }
11
+ /**
12
+ * Throw unless the export's schemaVersion is one this package reads.
13
+ * @param path the export's path, for the message
14
+ */
15
+ export function checkSchemaVersion(version, path) {
16
+ if (typeof version === 'number' && SUPPORTED_SCHEMA_VERSIONS.includes(version))
17
+ return;
18
+ throw new PlanningExportError(`${path} has schemaVersion ${String(version)}; this site reads schemaVersion ${SUPPORTED_SCHEMA_VERSIONS.join(', ')}.`);
19
+ }
@@ -0,0 +1,10 @@
1
+ import type { ResolvedOptions } from './types.js';
2
+ export type SidebarItem = string | {
3
+ label: string;
4
+ link: string;
5
+ } | {
6
+ label: string;
7
+ items: SidebarItem[];
8
+ collapsed?: boolean;
9
+ };
10
+ export declare function buildSidebar(options: ResolvedOptions): SidebarItem[];
@@ -0,0 +1,30 @@
1
+ // The Starlight sidebar: the plan, its optional views switched on in the
2
+ // options, then one group per docs source that has pages.
3
+ import { pagesOf } from "./repo-docs.js";
4
+ export function buildSidebar(options) {
5
+ const { views, docs } = options;
6
+ const plan = [
7
+ views.now && { label: 'Now', link: '/plan/now/' },
8
+ { label: 'Board', link: '/plan/board/' },
9
+ { label: 'Roadmap', link: '/plan/roadmap/' },
10
+ views.milestones && { label: 'Milestones', link: '/plan/milestones/' },
11
+ views.features && { label: 'Features', link: '/plan/features/' },
12
+ { label: 'Log', link: '/plan/log/' },
13
+ { label: 'Risks', link: '/plan/risks/' },
14
+ views.inbox && { label: 'Inbox', link: '/plan/inbox/' },
15
+ views.briefs && { label: 'Briefs', link: '/plan/briefs/' },
16
+ views.strategy && { label: 'Strategy', link: '/plan/strategy/' },
17
+ ];
18
+ const groups = docs
19
+ ? docs.sources
20
+ .filter((source) => !source.hidden)
21
+ .map((source) => ({
22
+ label: source.label,
23
+ collapsed: source.collapsed ?? false,
24
+ items: pagesOf(source, docs.root).map((page) => page.id),
25
+ }))
26
+ // Starlight rejects an empty group.
27
+ .filter((group) => group.items.length > 0)
28
+ : [];
29
+ return [{ label: 'Plan', items: plan.filter((item) => item !== false) }, ...groups];
30
+ }
@@ -0,0 +1,9 @@
1
+ import type { PmDocsSiteOptions } from './types.js';
2
+ /** @param siteDir absolute */
3
+ export declare function loadSiteOptions(siteDir: string, flags: {
4
+ title?: string;
5
+ planning?: string;
6
+ }): Promise<{
7
+ options: PmDocsSiteOptions;
8
+ configFile: string | null;
9
+ }>;
@@ -0,0 +1,39 @@
1
+ // The options a site gives the integration, read the way the CLI needs them:
2
+ // from its astro.config file when it has one, else from command-line flags.
3
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
4
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
5
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
6
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
7
+ });
8
+ }
9
+ return path;
10
+ };
11
+ import { existsSync } from 'node:fs';
12
+ import { join } from 'node:path';
13
+ import { pathToFileURL } from 'node:url';
14
+ const CONFIG_FILES = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts'];
15
+ /** @param siteDir absolute */
16
+ export async function loadSiteOptions(siteDir, flags) {
17
+ const configFile = CONFIG_FILES.map((name) => join(siteDir, name)).find((file) => existsSync(file)) ?? null;
18
+ if (!configFile) {
19
+ return {
20
+ options: { title: flags.title ?? 'Project plan', ...(flags.planning ? { planning: flags.planning } : {}) },
21
+ configFile: null,
22
+ };
23
+ }
24
+ // Plain Node loads the config, so a TypeScript config may only use what Node
25
+ // strips: erasable syntax and relative imports that name their file.
26
+ let config;
27
+ try {
28
+ config = (await import(__rewriteRelativeImportExtension(pathToFileURL(configFile).href))).default ?? {};
29
+ }
30
+ catch (error) {
31
+ throw new Error(`pm-docs-site: could not load ${configFile} under Node (${error.message.trim()}). ` +
32
+ 'Keep astro.config.ts to erasable TypeScript, with explicit .ts extensions on relative imports.');
33
+ }
34
+ const integrations = (Array.isArray(config.integrations) ? config.integrations : []).flat(Infinity);
35
+ const ours = integrations.find((entry) => entry?.name === 'pm-docs-site');
36
+ if (!ours?.pmDocsSiteOptions)
37
+ throw new Error(`pm-docs-site: no pm-docs-site integration in ${configFile}`);
38
+ return { options: ours.pmDocsSiteOptions, configFile };
39
+ }