uncial-cms 2.0.1 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 David A. Flood
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -13,6 +13,11 @@ export interface DoctorOptions {
13
13
  appSlug?: string;
14
14
  /** Ref the Allowlist is read from; defaults to the repository's default branch. */
15
15
  branch?: string;
16
+ /**
17
+ * Probe GitHub Pages. A site deployed anywhere else opts out explicitly, so
18
+ * that a Pages site which is genuinely misconfigured still fails the check.
19
+ */
20
+ pages?: boolean;
16
21
  }
17
22
  /** Runs the real `gh`. A missing binary is a non-zero status, not an exception. */
18
23
  export declare function ghCli(): GhInvoker;
@@ -209,7 +209,12 @@ export async function doctor(options, io, gh = ghCli()) {
209
209
  await checkAppInstalled(gh, report, repo, appSlug);
210
210
  await checkPushPermission(gh, report, repo);
211
211
  await checkAllowlist(gh, report, repo, origin.origin, options.branch);
212
- await checkPages(gh, report, repo, origin.host);
212
+ if (options.pages === false) {
213
+ report.warn('skipped the GitHub Pages probe (--no-pages): this site deploys elsewhere.');
214
+ }
215
+ else {
216
+ await checkPages(gh, report, repo, origin.host);
217
+ }
213
218
  if (origin.host.endsWith('.github.io')) {
214
219
  report.warn(`${origin.host} is a shared origin: allowlisting it authorises every project page served from it. A custom domain restores per-site granularity.`);
215
220
  }
package/dist/cli/run.js CHANGED
@@ -15,7 +15,7 @@ Usage:
15
15
  CMS runtime sentinel or the editor stack.
16
16
 
17
17
  uncial-cms doctor --origin <https://host> [--repo owner/name]
18
- [--app-slug <slug>] [--branch <ref>]
18
+ [--app-slug <slug>] [--branch <ref>] [--no-pages]
19
19
 
20
20
  Check, through the authenticated \`gh\` CLI, that the GitHub App is
21
21
  installed on the repository, that .uncial/cms.json is committed and lists
@@ -26,6 +26,7 @@ Usage:
26
26
  --repo Defaults to the repository of the current checkout.
27
27
  --app-slug Defaults to "${DEFAULT_APP_SLUG}".
28
28
  --branch Ref the allowlist is read from; defaults to the default branch.
29
+ --no-pages Skip the Pages probe, for a site deployed somewhere else.
29
30
 
30
31
  uncial-cms --help Print this message.`;
31
32
  export const consoleOutput = {
@@ -33,24 +34,29 @@ export const consoleOutput = {
33
34
  err: (line) => console.error(line)
34
35
  };
35
36
  /** Flags taking a value, in either `--flag value` or `--flag=value` form. */
36
- function parseFlags(rest, names) {
37
+ function parseFlags(rest, names, booleans = []) {
37
38
  const values = {};
39
+ const flags = new Set();
38
40
  for (let i = 0; i < rest.length; i += 1) {
39
41
  const arg = rest[i];
42
+ if (booleans.includes(arg)) {
43
+ flags.add(arg);
44
+ continue;
45
+ }
40
46
  const [name, inline] = arg.startsWith('--') && arg.includes('=')
41
47
  ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)]
42
48
  : [arg, undefined];
43
49
  if (!names.includes(name))
44
- return { values, error: `Unknown option "${arg}".` };
50
+ return { values, flags, error: `Unknown option "${arg}".` };
45
51
  const value = inline ?? rest[i + 1];
46
52
  if (value === undefined || value.startsWith('-')) {
47
- return { values, error: `Option "${name}" needs a value.` };
53
+ return { values, flags, error: `Option "${name}" needs a value.` };
48
54
  }
49
55
  if (inline === undefined)
50
56
  i += 1;
51
57
  values[name] = value;
52
58
  }
53
- return { values, error: null };
59
+ return { values, flags, error: null };
54
60
  }
55
61
  export async function run(argv, io = consoleOutput, gh) {
56
62
  const [command, ...rest] = argv;
@@ -68,7 +74,7 @@ export async function run(argv, io = consoleOutput, gh) {
68
74
  return 0;
69
75
  }
70
76
  if (command === 'doctor') {
71
- const { values, error } = parseFlags(rest, ['--origin', '--repo', '--app-slug', '--branch']);
77
+ const { values, flags, error } = parseFlags(rest, ['--origin', '--repo', '--app-slug', '--branch'], ['--no-pages']);
72
78
  if (error !== null) {
73
79
  io.err(error);
74
80
  io.err(USAGE);
@@ -84,7 +90,8 @@ export async function run(argv, io = consoleOutput, gh) {
84
90
  origin,
85
91
  repo: values['--repo'],
86
92
  appSlug: values['--app-slug'],
87
- branch: values['--branch']
93
+ branch: values['--branch'],
94
+ pages: !flags.has('--no-pages')
88
95
  }, io, gh);
89
96
  }
90
97
  const localOnly = rest.includes('--local-only');
@@ -3,6 +3,7 @@
3
3
  * build: the local forge while developing, the declared GitHub forge in a
4
4
  * production build, and a local-only site when no GitHub half is declared.
5
5
  */
6
+ import { type DeployStatusTimings } from './deploy-status.js';
6
7
  import type { UncialCmsSiteConfig } from './types.js';
7
8
  /** The auth worker this project operates for sites using the canonical GitHub App. */
8
9
  export declare const DEFAULT_AUTH_WORKER_URL = "https://uncial-cms-auth.dflood.workers.dev";
@@ -24,6 +25,12 @@ export interface SiteOptions {
24
25
  };
25
26
  /** Honoured only when the resolved forge is local; a forge commit is never autosaved. */
26
27
  autosaveMs?: number;
28
+ /**
29
+ * How long the post-save status line waits on the pipeline. A site whose
30
+ * build outlasts the default five-minute timeout says so here, or every save
31
+ * ends on "status unknown". Each field falls back to its default.
32
+ */
33
+ deployStatus?: Partial<DeployStatusTimings>;
27
34
  }
28
35
  export interface Site {
29
36
  config: UncialCmsSiteConfig;
@@ -31,6 +38,7 @@ export interface Site {
31
38
  localOnly: boolean;
32
39
  autosaveMs: number | undefined;
33
40
  localContentDir: string;
41
+ deployStatusTimings: DeployStatusTimings;
34
42
  }
35
43
  export declare function defineSite(options: SiteOptions, env?: {
36
44
  dev: boolean;
@@ -1,7 +1,20 @@
1
+ /**
2
+ * One declaration of a site's CMS configuration, resolved for the current
3
+ * build: the local forge while developing, the declared GitHub forge in a
4
+ * production build, and a local-only site when no GitHub half is declared.
5
+ */
6
+ import { DEFAULT_DEPLOY_STATUS_TIMINGS } from './deploy-status.js';
1
7
  /** The auth worker this project operates for sites using the canonical GitHub App. */
2
8
  export const DEFAULT_AUTH_WORKER_URL = 'https://uncial-cms-auth.dflood.workers.dev';
3
9
  /** The canonical GitHub App a site installs on its repository. */
4
10
  export const DEFAULT_APP_SLUG = 'uncial-cms';
11
+ function resolveDeployStatusTimings(overrides = {}) {
12
+ return {
13
+ firstDelayMs: overrides.firstDelayMs ?? DEFAULT_DEPLOY_STATUS_TIMINGS.firstDelayMs,
14
+ intervalMs: overrides.intervalMs ?? DEFAULT_DEPLOY_STATUS_TIMINGS.intervalMs,
15
+ timeoutMs: overrides.timeoutMs ?? DEFAULT_DEPLOY_STATUS_TIMINGS.timeoutMs
16
+ };
17
+ }
5
18
  export function defineSite(options, env = { dev: import.meta.env.DEV }) {
6
19
  const localOnly = options.github === undefined;
7
20
  const config = env.dev || options.github === undefined
@@ -19,6 +32,7 @@ export function defineSite(options, env = { dev: import.meta.env.DEV }) {
19
32
  config,
20
33
  localOnly,
21
34
  autosaveMs: config.forge === 'local' ? options.autosaveMs : undefined,
22
- localContentDir: options.localContentDir ?? options.contentDir
35
+ localContentDir: options.localContentDir ?? options.contentDir,
36
+ deployStatusTimings: resolveDeployStatusTimings(options.deployStatus)
23
37
  };
24
38
  }
@@ -21,6 +21,7 @@
21
21
  * its own corrections to that stylesheet.
22
22
  */
23
23
  import { type EditorController, type EditorPageUi } from './editor-controller.js';
24
+ import type { DeployStatusTimings, Schedule } from './deploy-status.js';
24
25
  import type { BlockRegistry, ContentSchema } from 'uncial/core';
25
26
  import type { ForgeAdapter, SessionProvider, UncialCmsSiteConfig } from './types.js';
26
27
  export type { DownloadPayload, EditorController, EditorPageUi, StatusView } from './editor-controller.js';
@@ -54,6 +55,13 @@ export interface CreateEditorSessionOptions {
54
55
  }) => void;
55
56
  /** True once the host's surface has been torn down. */
56
57
  isDestroyed?: () => boolean;
58
+ /**
59
+ * Deploy-status polling cadence and deadline; `defineSite` resolves these
60
+ * onto `Site.deployStatusTimings`. Omitted uses the defaults.
61
+ */
62
+ timings?: DeployStatusTimings;
63
+ /** Timer injection point; tests drive polling without real delays. */
64
+ schedule?: Schedule;
57
65
  }
58
66
  export declare function forgeAdapter(config: UncialCmsSiteConfig): ForgeAdapter;
59
67
  export declare function defaultSessionProvider(config: UncialCmsSiteConfig): SessionProvider;
@@ -58,6 +58,8 @@ export function createEditorSession(opts) {
58
58
  confirm: opts.confirm ?? ((message) => window.confirm(message)),
59
59
  download: opts.download ?? triggerDownload,
60
60
  autosaveMs: opts.autosaveMs,
61
+ timings: opts.timings,
62
+ schedule: opts.schedule,
61
63
  isDestroyed: opts.isDestroyed
62
64
  });
63
65
  }
@@ -75,17 +75,76 @@ class GitHubAdapter {
75
75
  .filter((entry) => entry.type === 'file' || entry.type === 'dir')
76
76
  .map((entry) => ({ path: entry.path, type: entry.type }));
77
77
  }
78
+ /**
79
+ * Both of GitHub's two answers to "how did this commit fare", because a repo
80
+ * may use either.
81
+ *
82
+ * ⚠ The combined Status API aggregates the *Status* API alone, and GitHub
83
+ * Actions writes **check runs**, not statuses. A repository built by Actions
84
+ * — which is every Pages site deployed from a workflow — therefore has
85
+ * `state: "pending"` and an empty `statuses` array on that endpoint for
86
+ * ever, and a poll that trusted it would sit at "building…" through a deploy
87
+ * that has already succeeded. So an empty `statuses` is read as *no signal*
88
+ * rather than as pending, and the check runs are asked as well.
89
+ */
78
90
  async commitStatus(commitSha) {
79
- const response = await this.#request(`${GITHUB_API_URL}/repos/${this.#config.repo}/commits/${encodeURIComponent(commitSha)}/status`);
91
+ const sha = encodeURIComponent(commitSha);
92
+ const base = `${GITHUB_API_URL}/repos/${this.#config.repo}/commits/${sha}`;
93
+ const [fromStatuses, fromChecks] = await Promise.all([
94
+ this.#statusApiSignal(`${base}/status`),
95
+ this.#checkRunSignal(`${base}/check-runs`)
96
+ ]);
97
+ const signals = [fromStatuses, fromChecks].filter((signal) => signal !== 'unknown');
98
+ if (signals.includes('failure'))
99
+ return 'failure';
100
+ if (signals.includes('pending'))
101
+ return 'pending';
102
+ return signals.includes('success') ? 'success' : 'unknown';
103
+ }
104
+ async #statusApiSignal(url) {
105
+ const response = await this.#request(url);
80
106
  if (!response.ok)
81
107
  return 'unknown';
82
- const { state } = (await response.json());
108
+ const { state, statuses } = (await response.json());
109
+ if ((statuses ?? []).length === 0)
110
+ return 'unknown';
83
111
  if (state === 'pending' || state === 'success')
84
112
  return state;
85
113
  if (state === 'failure' || state === 'error')
86
114
  return 'failure';
87
115
  return 'unknown';
88
116
  }
117
+ async #checkRunSignal(url) {
118
+ const response = await this.#request(url);
119
+ if (!response.ok)
120
+ return 'unknown';
121
+ const { check_runs: runs } = (await response.json());
122
+ if (!runs || runs.length === 0)
123
+ return 'unknown';
124
+ let pending = false;
125
+ let success = false;
126
+ for (const run of runs) {
127
+ if (run.status !== 'completed') {
128
+ pending = true;
129
+ continue;
130
+ }
131
+ switch (run.conclusion) {
132
+ case 'success':
133
+ case 'neutral':
134
+ case 'skipped':
135
+ success = true;
136
+ break;
137
+ // A run superseded by a later one says nothing about this commit.
138
+ case 'stale':
139
+ break;
140
+ default:
141
+ return 'failure';
142
+ }
143
+ }
144
+ if (pending)
145
+ return 'pending';
146
+ return success ? 'success' : 'unknown';
147
+ }
89
148
  #contentsUrl(path) {
90
149
  return `${GITHUB_API_URL}/repos/${this.#config.repo}/contents/${encodeRepoPath(path)}`;
91
150
  }
@@ -101,6 +101,7 @@
101
101
  schema: resolvedSchema,
102
102
  sessionProvider,
103
103
  autosaveMs: site.autosaveMs,
104
+ timings: site.deployStatusTimings,
104
105
  isDestroyed: () => cancelled,
105
106
  ui: {
106
107
  status: (view) => (status = view),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uncial-cms",
3
- "version": "2.0.1",
3
+ "version": "3.0.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -64,7 +64,7 @@
64
64
  "peerDependencies": {
65
65
  "@sveltejs/kit": "^2.0.0",
66
66
  "svelte": "^5.0.0",
67
- "uncial": "^2.0.1"
67
+ "uncial": "^3.0.0"
68
68
  },
69
69
  "peerDependenciesMeta": {
70
70
  "@sveltejs/kit": {