Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8045 Mint v2 share links behind reader gate (#3620)

serafin-garciab2b06a46c70b
diff --git a/.changeset/share-nested-content-links.md b/.changeset/share-nested-content-links.md
new file mode 100644
index 000000000..38b2f50e7
--- /dev/null
+++ b/.changeset/share-nested-content-links.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-server": patch
+---
+
+Share links now preserve nested `content.dir` roots in their GitHub source URL while decoding back to the same content-relative document or folder. Release and deployment gates also prevent a pre-v2 reader from serving or shipping after v2 link minting begins.
diff --git a/.github/composite-actions/share-contract-reader-gate/README.md b/.github/composite-actions/share-contract-reader-gate/README.md
new file mode 100644
index 000000000..5607b6ecf
--- /dev/null
+++ b/.github/composite-actions/share-contract-reader-gate/README.md
@@ -0,0 +1,11 @@
+# Share contract reader gate
+
+This composite action blocks a release or deployment when the deployed Open Knowledge reader cannot consume the fixed v2 share corpus.
+
+It runs `.github/scripts/probe-share-contract.mjs`, records the contract epoch, corpus digest, deployment SHA, and fixed-case results in the job summary, and uploads the JSON evidence even when the probe fails.
+
+Inputs:
+
+- `origin`: absolute deployment origin to probe.
+- `expected-deployment-sha`: optional SHA that the reader manifest must report.
+- `evidence-name`: artifact name for the JSON evidence.
diff --git a/.github/composite-actions/share-contract-reader-gate/action.yml b/.github/composite-actions/share-contract-reader-gate/action.yml
new file mode 100644
index 000000000..c57d2f157
--- /dev/null
+++ b/.github/composite-actions/share-contract-reader-gate/action.yml
@@ -0,0 +1,76 @@
+name: Share contract reader gate
+description: Attest that a deployed Open Knowledge reader accepts the fixed v2 share corpus.
+
+inputs:
+ origin:
+ description: Absolute deployment origin to probe.
+ required: true
+ expected-deployment-sha:
+ description: Optional deployment SHA that the reader manifest must report.
+ required: false
+ default: ""
+ evidence-name:
+ description: Name for the uploaded evidence artifact.
+ required: true
+
+runs:
+ using: composite
+ steps:
+ - name: Set up Node
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: "24"
+
+ - name: Probe reader compatibility
+ id: probe
+ continue-on-error: true
+ shell: bash
+ env:
+ ORIGIN: ${{ inputs.origin }}
+ EXPECTED_DEPLOYMENT_SHA: ${{ inputs.expected-deployment-sha }}
+ EVIDENCE_PATH: ${{ runner.temp }}/share-contract-evidence.json
+ run: |
+ set -euo pipefail
+ args=(
+ --origin "$ORIGIN"
+ --corpus "$GITHUB_ACTION_PATH/../../../test-support/fixtures/share-url-v1-v2.json"
+ --evidence "$EVIDENCE_PATH"
+ )
+ if [[ -n "$EXPECTED_DEPLOYMENT_SHA" ]]; then
+ args+=(--expected-deployment-sha "$EXPECTED_DEPLOYMENT_SHA")
+ fi
+ node "$GITHUB_ACTION_PATH/../../scripts/probe-share-contract.mjs" "${args[@]}"
+
+ - name: Record reader-contract evidence
+ if: always()
+ shell: bash
+ env:
+ EVIDENCE_PATH: ${{ runner.temp }}/share-contract-evidence.json
+ run: |
+ set -euo pipefail
+ {
+ echo "### Share-contract reader attestation"
+ if [[ ! -f "$EVIDENCE_PATH" ]]; then
+ echo "- Evidence: missing"
+ else
+ echo "- Status: \`$(jq -r '.status // "unknown"' "$EVIDENCE_PATH")\`"
+ echo "- Epoch: \`$(jq -r '.epoch // "unavailable"' "$EVIDENCE_PATH")\`"
+ echo "- Corpus SHA-256: \`$(jq -r '.corpusSha256 // "unavailable"' "$EVIDENCE_PATH")\`"
+ echo "- Deployment SHA: \`$(jq -r '.deploymentSha // "unavailable"' "$EVIDENCE_PATH")\`"
+ echo "- Probes: \`$(jq -r '[.probes[]?.id] | join(", ") // "unavailable"' "$EVIDENCE_PATH")\`"
+ fi
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ - name: Upload reader-contract evidence
+ if: always()
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: ${{ inputs.evidence-name }}
+ path: ${{ runner.temp }}/share-contract-evidence.json
+ retention-days: 30
+ if-no-files-found: error
+
+ - name: Refuse an incompatible reader
+ if: always() && steps.probe.outcome == 'failure'
+ shell: bash
+ run: exit 1
diff --git a/.github/scripts/probe-share-contract.mjs b/.github/scripts/probe-share-contract.mjs
index f680b7fa2..7ae5d6707 100644
--- a/.github/scripts/probe-share-contract.mjs
+++ b/.github/scripts/probe-share-contract.mjs
@@ -55,9 +55,10 @@ function fail(code, message, now, manifest, probeId) {
}
function normalizeOrigin(origin) {
+ const candidate = /^[A-Za-z][A-Za-z\d+.-]*:/.test(origin) ? origin : `https://${origin}`;
let parsed;
try {
- parsed = new URL(origin);
+ parsed = new URL(candidate);
} catch {
throw new Error('origin must be an absolute HTTP(S) URL');
}
diff --git a/.github/scripts/probe-share-contract.test.mjs b/.github/scripts/probe-share-contract.test.mjs
index c7f8574a0..8aa46bf29 100644
--- a/.github/scripts/probe-share-contract.test.mjs
+++ b/.github/scripts/probe-share-contract.test.mjs
@@ -132,6 +132,38 @@ describe('share-contract reader probe', () => {
}
});
+ test('normalizes a scheme-less Vercel deployment URL to HTTPS', async () => {
+ const reader = compatibleReader();
+ const requestedUrls = [];
+ const fetchImpl = async (input) => {
+ const url = new URL(String(input));
+ requestedUrls.push(url.href);
+ if (url.pathname === '/.well-known/openknowledge-share-contract.json') {
+ return new Response(JSON.stringify(reader.manifest), {
+ headers: { 'content-type': 'application/json' },
+ });
+ }
+ const page = reader.pages.get(url.pathname);
+ return page === undefined
+ ? new Response('missing', { status: 404 })
+ : new Response(page, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+ };
+
+ const evidence = await probeShareContract({
+ origin: 'reader.example.vercel.app',
+ corpus: CORPUS,
+ corpusBytes: CORPUS_BYTES,
+ expectedDeploymentSha: EXPECTED_DEPLOYMENT_SHA,
+ fetchImpl,
+ });
+
+ expect(evidence.status).toBe('compatible');
+ expect(requestedUrls).not.toHaveLength(0);
+ expect(requestedUrls.every((url) => url.startsWith('https://reader.example.vercel.app/'))).toBe(
+ true,
+ );
+ });
+
test('retries once past a transient network blip on the first fetch', async () => {
const origin = await startReader(compatibleReader());
let attempts = 0;
diff --git a/.github/scripts/share-contract-reader-gates-shape.test.mjs b/.github/scripts/share-contract-reader-gates-shape.test.mjs
new file mode 100644
index 000000000..c0f5c8c50
--- /dev/null
+++ b/.github/scripts/share-contract-reader-gates-shape.test.mjs
@@ -0,0 +1,157 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+
+const githubDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function readGithubFile(...segments) {
+ return readFileSync(join(githubDir, ...segments), 'utf8');
+}
+
+function workflowExpression(expression) {
+ return `\${{ ${expression} }}`;
+}
+
+/**
+ * Slice one step's block (from its `- name:` line to the next step) so
+ * fail-safe attributes are asserted on the step they protect, not merely
+ * somewhere in the file — `continue-on-error` on the wrong step would keep a
+ * whole-file `toContain` green while probe failures abort before evidence.
+ */
+function stepBlock(source, stepName) {
+ const block = source.split(/^\s*- name: /m).find((candidate) => candidate.startsWith(stepName));
+ if (!block) throw new Error(`step not found: ${stepName}`);
+ return block;
+}
+
+const composite = readGithubFile('composite-actions', 'share-contract-reader-gate', 'action.yml');
+const deploymentGate = readGithubFile('workflows', 'share-contract-deployment-gate.yml');
+
+const releaseLanes = [
+ {
+ name: 'beta and npm release',
+ workflow: readGithubFile('workflows', 'release.yml'),
+ gate: 'Attest production reader before release',
+ mutation: ' - name: Tag + create prerelease GitHub Release',
+ condition:
+ "if: github.event.action == 'publish-stable' || steps.compute-beta.outputs.run_beta == 'true'",
+ },
+ {
+ name: 'stable promotion',
+ workflow: readGithubFile('workflows', 'promote-stable.yml'),
+ gate: 'Attest production reader before promotion',
+ mutation: ' - name: Tag stable at beta SHA',
+ condition: "if: steps.ver.outputs.skip != 'true'",
+ },
+ {
+ name: 'point release',
+ workflow: readGithubFile('workflows', 'point-release.yml'),
+ gate: 'Attest production reader before point release',
+ mutation: ' - name: Run the point release',
+ condition: 'if: inputs.dry_run == false',
+ },
+];
+
+describe('share-contract reader gate composite', () => {
+ test('runs the canonical probe against the fixed corpus with SHA pinning available', () => {
+ const probe = stepBlock(composite, 'Probe reader compatibility');
+ expect(probe).toContain('id: probe');
+ expect(probe).toContain('probe-share-contract.mjs');
+ expect(probe).toContain('test-support/fixtures/share-url-v1-v2.json');
+ expect(probe).toContain('--expected-deployment-sha');
+ });
+
+ test('a probe failure cannot skip evidence: probe continues, evidence always lands, gate still fails', () => {
+ expect(stepBlock(composite, 'Probe reader compatibility')).toContain('continue-on-error: true');
+ expect(stepBlock(composite, 'Record reader-contract evidence')).toContain('if: always()');
+ const upload = stepBlock(composite, 'Upload reader-contract evidence');
+ expect(upload).toContain('if: always()');
+ expect(upload).toContain('actions/upload-artifact@');
+ expect(upload).toContain('if-no-files-found: error');
+ expect(stepBlock(composite, 'Refuse an incompatible reader')).toContain(
+ "if: always() && steps.probe.outcome == 'failure'",
+ );
+ });
+
+ test('records every required attestation field in the run summary', () => {
+ const record = stepBlock(composite, 'Record reader-contract evidence');
+ for (const field of ['.status', '.epoch', '.corpusSha256', '.deploymentSha', '.probes']) {
+ expect(record).toContain(field);
+ }
+ });
+});
+
+describe('share-contract candidate deployment gate', () => {
+ test('targets only the production docs project and supports manual verification', () => {
+ expect(deploymentGate).toContain('types: [vercel.deployment.ready]');
+ expect(deploymentGate).toContain('workflow_dispatch:');
+ expect(deploymentGate).toContain("github.event.client_payload.environment == 'production'");
+ expect(deploymentGate).toContain(
+ "github.event.client_payload.project.name == 'open-knowledge-docs'",
+ );
+ expect(deploymentGate).toContain('name: share-contract-v2-runner');
+ expect(deploymentGate).not.toContain('name: share-contract-v2\n');
+ });
+
+ test('checks out and probes the candidate deployment, not production', () => {
+ expect(stepBlock(deploymentGate, 'Checkout candidate deployment SHA')).toContain(
+ `ref: ${workflowExpression('github.event.client_payload.git.sha || github.sha')}`,
+ );
+ const probe = stepBlock(deploymentGate, 'Probe candidate reader contract');
+ expect(probe).toContain('id: reader');
+ expect(probe).toContain('continue-on-error: true');
+ expect(probe).toContain(
+ `origin: ${workflowExpression('github.event.client_payload.url || inputs.origin')}`,
+ );
+ expect(probe).toContain(
+ `expected-deployment-sha: ${workflowExpression(
+ 'github.event.client_payload.git.sha || inputs.expected_deployment_sha',
+ )}`,
+ );
+ });
+
+ test('reports the exact Vercel status on every outcome and refuses an incompatible candidate', () => {
+ expect(deploymentGate).toContain('statuses: write');
+ expect(deploymentGate.match(/context=share-contract-v2/g)).toHaveLength(2);
+ expect(stepBlock(deploymentGate, 'Report candidate reader result to Vercel')).toContain(
+ "if: always() && github.event_name == 'repository_dispatch'",
+ );
+ expect(stepBlock(deploymentGate, 'Refuse an incompatible candidate')).toContain(
+ "if: always() && steps.reader.outcome == 'failure'",
+ );
+ });
+});
+
+describe.each(releaseLanes)('$name reader attestation', ({
+ workflow,
+ gate,
+ mutation,
+ condition,
+}) => {
+ test('blocks before the first release mutation and skips only no-op lanes', () => {
+ const gateIndex = workflow.indexOf(
+ 'uses: ./.github/composite-actions/share-contract-reader-gate',
+ );
+ const mutationIndex = workflow.indexOf(mutation);
+ expect(gateIndex).toBeGreaterThan(-1);
+ expect(mutationIndex).toBeGreaterThan(-1);
+ expect(gateIndex).toBeLessThan(mutationIndex);
+ expect(stepBlock(workflow, gate)).toContain(condition);
+ });
+});
+
+describe('stable release reader attestation', () => {
+ test('restores the local composite action and its inputs from the workflow revision', () => {
+ const release = readGithubFile('workflows', 'release.yml');
+ const restore = stepBlock(release, 'Restore reader gate from workflow revision');
+ expect(restore).toContain("if: github.event.action == 'publish-stable'");
+ expect(restore).toContain('git checkout "$GITHUB_SHA" --');
+ expect(restore).toContain('.github/composite-actions/share-contract-reader-gate/action.yml');
+ expect(restore).toContain('.github/scripts/probe-share-contract.mjs');
+ expect(restore).toContain('test-support/fixtures/share-url-v1-v2.json');
+ expect(release.indexOf('- name: Restore reader gate from workflow revision')).toBeLessThan(
+ release.indexOf('- name: Attest production reader before release'),
+ );
+ });
+});
diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.yml
index 0c1740b63..fff2dea3b 100644
--- a/.github/workflows/point-release.yml
+++ b/.github/workflows/point-release.yml
@@ -193,6 +193,13 @@ jobs:
owner: inkeep
repositories: agents-private
+ - name: Attest production reader before point release
+ if: inputs.dry_run == false
+ uses: ./.github/composite-actions/share-contract-reader-gate
+ with:
+ origin: https://openknowledge.ai
+ evidence-name: share-contract-point-release-${{ github.run_id }}-${{ github.run_attempt }}
+
- name: Run the point release
id: plan
env:
diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml
index bb6726c5a..babe5eb61 100644
--- a/.github/workflows/promote-stable.yml
+++ b/.github/workflows/promote-stable.yml
@@ -257,6 +257,13 @@ jobs:
echo "Triggered manually or by external repository_dispatch." >> "$GITHUB_STEP_SUMMARY"
fi
+ - name: Attest production reader before promotion
+ if: steps.ver.outputs.skip != 'true'
+ uses: ./.github/composite-actions/share-contract-reader-gate
+ with:
+ origin: https://openknowledge.ai
+ evidence-name: share-contract-promote-${{ github.run_id }}-${{ github.run_attempt }}
+
- name: Tag stable at beta SHA
if: steps.ver.outputs.skip != 'true'
env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 33ef3aa40..aa6aef835 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -152,6 +152,15 @@ jobs:
# fix from Linear PRD-6701).
ref: ${{ github.event.client_payload.ref || github.sha }}
+ - name: Restore reader gate from workflow revision
+ if: github.event.action == 'publish-stable'
+ run: |
+ set -euo pipefail
+ git checkout "$GITHUB_SHA" -- \
+ .github/composite-actions/share-contract-reader-gate/action.yml \
+ .github/scripts/probe-share-contract.mjs \
+ test-support/fixtures/share-url-v1-v2.json
+
- uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5
- name: Get pnpm store directory
shell: bash
@@ -418,6 +427,13 @@ jobs:
echo "tag=$TAG"
} >> "$GITHUB_OUTPUT"
+ - name: Attest production reader before release
+ if: github.event.action == 'publish-stable' || steps.compute-beta.outputs.run_beta == 'true'
+ uses: ./.github/composite-actions/share-contract-reader-gate
+ with:
+ origin: https://openknowledge.ai
+ evidence-name: share-contract-release-${{ github.run_id }}-${{ github.run_attempt }}
+
- name: Override fixed-group versions to X.Y.Z-beta.N
if: steps.compute-beta.outputs.run_beta == 'true'
env:
diff --git a/.github/workflows/share-contract-deployment-gate.yml b/.github/workflows/share-contract-deployment-gate.yml
new file mode 100644
index 000000000..fa9aea780
--- /dev/null
+++ b/.github/workflows/share-contract-deployment-gate.yml
@@ -0,0 +1,88 @@
+name: Share contract deployment gate
+
+on:
+ repository_dispatch:
+ types: [vercel.deployment.ready]
+ workflow_dispatch:
+ inputs:
+ origin:
+ description: Absolute deployment origin to probe.
+ required: true
+ type: string
+ expected_deployment_sha:
+ description: Optional SHA that the reader manifest must report.
+ required: false
+ type: string
+
+permissions:
+ contents: read
+ statuses: write
+
+concurrency:
+ group: share-contract-deployment-${{ github.event.client_payload.id || github.run_id }}
+ cancel-in-progress: false
+
+jobs:
+ reader-contract:
+ name: share-contract-v2-runner
+ if: >-
+ github.event_name == 'workflow_dispatch' ||
+ (github.event.client_payload.environment == 'production' &&
+ github.event.client_payload.project.name == 'open-knowledge-docs')
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - name: Mark candidate reader check pending
+ if: github.event_name == 'repository_dispatch'
+ env:
+ DEPLOYMENT_SHA: ${{ github.event.client_payload.git.sha }}
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+ run: |
+ set -euo pipefail
+ gh api --method POST "repos/${GITHUB_REPOSITORY}/statuses/${DEPLOYMENT_SHA}" \
+ -f state=pending \
+ -f context=share-contract-v2 \
+ -f description='Checking the v2 reader contract' \
+ -f target_url="$RUN_URL"
+
+ - name: Checkout candidate deployment SHA
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ ref: ${{ github.event.client_payload.git.sha || github.sha }}
+
+ - name: Probe candidate reader contract
+ id: reader
+ continue-on-error: true
+ uses: ./.github/composite-actions/share-contract-reader-gate
+ with:
+ origin: ${{ github.event.client_payload.url || inputs.origin }}
+ expected-deployment-sha: ${{ github.event.client_payload.git.sha || inputs.expected_deployment_sha }}
+ evidence-name: share-contract-candidate-${{ github.run_id }}-${{ github.run_attempt }}
+
+ - name: Report candidate reader result to Vercel
+ if: always() && github.event_name == 'repository_dispatch'
+ env:
+ DEPLOYMENT_SHA: ${{ github.event.client_payload.git.sha }}
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ READER_OUTCOME: ${{ steps.reader.outcome }}
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+ run: |
+ set -euo pipefail
+ if [[ "$READER_OUTCOME" == 'success' ]]; then
+ state=success
+ description='The candidate accepts the v2 share contract'
+ else
+ state=failure
+ description='The candidate rejects the v2 share contract'
+ fi
+ gh api --method POST "repos/${GITHUB_REPOSITORY}/statuses/${DEPLOYMENT_SHA}" \
+ -f state="$state" \
+ -f context=share-contract-v2 \
+ -f description="$description" \
+ -f target_url="$RUN_URL"
+
+ - name: Refuse an incompatible candidate
+ if: always() && steps.reader.outcome == 'failure'
+ run: exit 1
diff --git a/package.json b/package.json
index c70ef6abe..ea549fa51 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
"typecheck": "turbo run typecheck",
"test": "turbo run test",
"test:vitest-selftest": "vitest run",
+ "smoke:share-v2": "node --import tsx --conditions=development packages/server/share-v2-smoke.ts",
"lint": "pnpm run lint:biome && pnpm run lint:oxlint",
"lint:biome": "biome check packages docs *.json *.jsonc *.ts --error-on-warnings",
"lint:oxlint": "oxlint --max-warnings 0 .",
diff --git a/packages/app/src/lib/helper-string-catalog-parity.test.ts b/packages/app/src/lib/helper-string-catalog-parity.test.ts
index d1075353c..c155b12d8 100644
--- a/packages/app/src/lib/helper-string-catalog-parity.test.ts
+++ b/packages/app/src/lib/helper-string-catalog-parity.test.ts
@@ -47,7 +47,7 @@ const LOCALES_DIR = join(import.meta.dir, '..', 'locales', 'en');
* one" would stay green after all but one string was unwrapped.
*/
const MIGRATED_MODULES: ReadonlyArray<readonly [path: string, messages: number]> = [
- ['src/lib/share/run-share-action.ts', 10],
+ ['src/lib/share/run-share-action.ts', 11],
['src/lib/share/receive-flow.ts', 6],
['src/lib/share/publish-wizard.ts', 7],
['src/hooks/use-folder-config.ts', 2],
@@ -110,6 +110,7 @@ describe('helper messages round-trip to a catalog id with named placeholders', (
['share error: no branch name', () => mapShareErrorToToast('branch-not-on-origin')],
['share error: non-GitHub remote', () => mapShareErrorToToast('non-github-remote')],
['share error: unshareable path', () => mapShareErrorToToast('invalid-path')],
+ ['share error: unsupported share URL', () => mapShareErrorToToast('unsupported-share-url')],
['share error: no remote', () => mapShareErrorToToast('no-remote')],
[
'receive: folder is not a repository',
diff --git a/packages/app/src/lib/share/run-share-action.test.ts b/packages/app/src/lib/share/run-share-action.test.ts
index 599f0f161..eabf8c8ae 100644
--- a/packages/app/src/lib/share/run-share-action.test.ts
+++ b/packages/app/src/lib/share/run-share-action.test.ts
@@ -106,6 +106,10 @@ describe('mapShareErrorToToast', () => {
expect(mapShareErrorToToast('invalid-path')).toBe("Can't share this path.");
});
+ test('unsupported-share-url returns codec-neutral copy', () => {
+ expect(mapShareErrorToToast('unsupported-share-url')).toBe("This GitHub URL can't be shared.");
+ });
+
test('no-remote returns the no-remote copy (kept for callers that map directly; runShareAction routes to the wizard)', () => {
// `runShareAction` routes both client-side `hasRemote: false` AND
// server-side `{ok:false, error:'no-remote'}` to the Publish wizard.
@@ -122,6 +126,7 @@ describe('mapShareErrorToToast', () => {
'branch-not-on-origin',
'non-github-remote',
'invalid-path',
+ 'unsupported-share-url',
];
for (const code of codes) {
expect(mapShareErrorToToast(code).length).toBeGreaterThan(0);
diff --git a/packages/app/src/lib/share/run-share-action.ts b/packages/app/src/lib/share/run-share-action.ts
index 18cf8fac0..3719b7bb0 100644
--- a/packages/app/src/lib/share/run-share-action.ts
+++ b/packages/app/src/lib/share/run-share-action.ts
@@ -102,6 +102,8 @@ export function mapShareErrorToToast(error: ShareConstructUrlErrorCode, branch?:
return t`Sharing supports GitHub remotes only.`;
case 'invalid-path':
return t`Can't share this path.`;
+ case 'unsupported-share-url':
+ return t`This GitHub URL can't be shared.`;
case 'no-remote':
return t`This project has no GitHub remote.`;
}
diff --git a/packages/app/src/locales/ar/messages.json b/packages/app/src/locales/ar/messages.json
index 5fccedbf0..e8c5f4c87 100644
--- a/packages/app/src/locales/ar/messages.json
+++ b/packages/app/src/locales/ar/messages.json
@@ -4857,6 +4857,7 @@
],
"uVbUP8": ["الإعدادات…"],
"uY5Z7P": ["انتهت اللعبة · اضغط <0>مسافة</0> للعب مرة أخرى"],
+ "uYZTcW": ["لا يمكن مشاركة عنوان URL هذا على GitHub."],
"u_lS4C": ["اكتمل الاستنساخ — يجري فتح المشروع"],
"uaUc6t": ["إعادة تشغيل الخادم"],
"ubMwcO": ["انتهت جلسة الطرفية (الإشارة ", ["0"], ")."],
diff --git a/packages/app/src/locales/ar/messages.po b/packages/app/src/locales/ar/messages.po
index 3eb258034..abe6c4f2b 100644
--- a/packages/app/src/locales/ar/messages.po
+++ b/packages/app/src/locales/ar/messages.po
@@ -13085,6 +13085,10 @@ msgstr "هذا المجلد ليس نسخة من {expectedOwner}/{expectedRepo}.
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "هذا المجلد ليس على GitHub بعد. لن يعمل الرابط حتى يُدفع."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "لا يمكن مشاركة عنوان URL هذا على GitHub."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "هذه معاينة لـ {boldName} — مهارة مدمجة تُشحن مع Open Knowledge. وهي للقراءة فقط."
diff --git a/packages/app/src/locales/bn/messages.json b/packages/app/src/locales/bn/messages.json
index 0705f0c68..1d0d61f5a 100644
--- a/packages/app/src/locales/bn/messages.json
+++ b/packages/app/src/locales/bn/messages.json
@@ -4144,6 +4144,7 @@
"uUiiyC": ["এই রিপোজিটরিতে পুশ করার অনুমতি আপনার নেই। Follow তবুও আপনার অনুলিপি হালনাগাদ রাখতে পারে।"],
"uVbUP8": ["সেটিং…"],
"uY5Z7P": ["খেলা শেষ · আবার খেলতে <0>স্পেস</0> চাপুন"],
+ "uYZTcW": ["এই GitHub URL শেয়ার করা যাবে না।"],
"u_lS4C": ["ক্লোন সম্পূর্ণ — প্রকল্প খোলা হচ্ছে"],
"uaUc6t": ["সার্ভার পুনরায় চালু করুন"],
"ubMwcO": ["টার্মিনাল সেশন শেষ হয়েছে (সংকেত ", ["0"], ")।"],
diff --git a/packages/app/src/locales/bn/messages.po b/packages/app/src/locales/bn/messages.po
index 8f4fa264e..f3990d7f5 100644
--- a/packages/app/src/locales/bn/messages.po
+++ b/packages/app/src/locales/bn/messages.po
@@ -13081,6 +13081,10 @@ msgstr "এই ফোল্ডারটি {expectedOwner}/{expectedRepo}-এর
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "এই ফোল্ডারটি এখনও GitHub-এ নেই। এটি না পাঠানো পর্যন্ত লিংকটি কাজ করবে না।"
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "এই GitHub URL শেয়ার করা যাবে না।"
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "এটি {boldName}-এর একটি প্রাকদর্শন — Open Knowledge-এর সঙ্গে আসা একটি অন্তর্নির্মিত স্কিল। এটি শুধু পড়ার জন্য।"
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index e51c30e04..9d451a5af 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -4280,6 +4280,7 @@
],
"uVbUP8": ["Settings…"],
"uY5Z7P": ["Game over · press <0>Space</0> to play again"],
+ "uYZTcW": ["This GitHub URL can't be shared."],
"u_lS4C": ["Clone complete — opening project"],
"uaUc6t": ["Restart server"],
"ubMwcO": ["The terminal session ended (signal ", ["0"], ")."],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index f6996db6b..ff2d43ac3 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -13085,6 +13085,10 @@ msgstr "This folder isn't a clone of {expectedOwner}/{expectedRepo}. Pick a diff
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "This folder isn't on GitHub yet. The link won't work until it's pushed."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "This GitHub URL can't be shared."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
diff --git a/packages/app/src/locales/es/messages.json b/packages/app/src/locales/es/messages.json
index be7ebcb5f..8b79d4c92 100644
--- a/packages/app/src/locales/es/messages.json
+++ b/packages/app/src/locales/es/messages.json
@@ -4929,6 +4929,7 @@
],
"uVbUP8": ["Ajustes…"],
"uY5Z7P": ["Fin del juego · pulsa <0>Espacio</0> para jugar de nuevo"],
+ "uYZTcW": ["No se puede compartir esta URL de GitHub."],
"u_lS4C": ["Clonación completada: abriendo el proyecto"],
"uaUc6t": ["Reiniciar el servidor"],
"ubMwcO": ["La sesión de terminal terminó (señal ", ["0"], ")."],
diff --git a/packages/app/src/locales/es/messages.po b/packages/app/src/locales/es/messages.po
index 530d2414d..bef62aa9f 100644
--- a/packages/app/src/locales/es/messages.po
+++ b/packages/app/src/locales/es/messages.po
@@ -13085,6 +13085,10 @@ msgstr "Esta carpeta no es un clon de {expectedOwner}/{expectedRepo}. ¿Eliges o
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "Esta carpeta todavía no está en GitHub. El enlace no funcionará hasta que se suba."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "No se puede compartir esta URL de GitHub."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "Esto es una vista previa de {boldName}, una habilidad integrada que viene con Open Knowledge. Es de solo lectura."
diff --git a/packages/app/src/locales/fr/messages.json b/packages/app/src/locales/fr/messages.json
index 70072af86..2b33a379b 100644
--- a/packages/app/src/locales/fr/messages.json
+++ b/packages/app/src/locales/fr/messages.json
@@ -4983,6 +4983,7 @@
],
"uVbUP8": ["Paramètres…"],
"uY5Z7P": ["Partie terminée · appuyez sur <0>Espace</0> pour rejouer"],
+ "uYZTcW": ["Cette URL GitHub ne peut pas être partagée."],
"u_lS4C": ["Clonage terminé — ouverture du projet"],
"uaUc6t": ["Redémarrer le serveur"],
"ubMwcO": ["La session de terminal s'est terminée (signal ", ["0"], ")."],
diff --git a/packages/app/src/locales/fr/messages.po b/packages/app/src/locales/fr/messages.po
index 62421df2d..cb3cd3f67 100644
--- a/packages/app/src/locales/fr/messages.po
+++ b/packages/app/src/locales/fr/messages.po
@@ -13085,6 +13085,10 @@ msgstr "Ce dossier n'est pas un clone de {expectedOwner}/{expectedRepo}. Choisir
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "Ce dossier n'est pas encore sur GitHub. Le lien ne fonctionnera pas tant qu'il n'aura pas été poussé."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "Cette URL GitHub ne peut pas être partagée."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "Ceci est un aperçu de {boldName} — une compétence intégrée livrée avec Open Knowledge. Elle est en lecture seule."
diff --git a/packages/app/src/locales/hi/messages.json b/packages/app/src/locales/hi/messages.json
index a536b33c8..22f7f50f3 100644
--- a/packages/app/src/locales/hi/messages.json
+++ b/packages/app/src/locales/hi/messages.json
@@ -4140,6 +4140,7 @@
],
"uVbUP8": ["सेटिंग…"],
"uY5Z7P": ["खेल समाप्त · फिर से खेलने के लिए <0>स्पेस</0> दबाएँ"],
+ "uYZTcW": ["यह GitHub URL साझा नहीं किया जा सकता।"],
"u_lS4C": ["क्लोन पूर्ण — प्रोजेक्ट खोला जा रहा है"],
"uaUc6t": ["सर्वर पुनः आरंभ करें"],
"ubMwcO": ["टर्मिनल सत्र समाप्त हो गया (सिग्नल ", ["0"], ")।"],
diff --git a/packages/app/src/locales/hi/messages.po b/packages/app/src/locales/hi/messages.po
index 04290ec60..fbabc1248 100644
--- a/packages/app/src/locales/hi/messages.po
+++ b/packages/app/src/locales/hi/messages.po
@@ -13081,6 +13081,10 @@ msgstr "यह फ़ोल्डर {expectedOwner}/{expectedRepo} का क
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "यह फ़ोल्डर अभी GitHub पर नहीं है। जब तक इसे भेजा नहीं जाता तब तक लिंक काम नहीं करेगा।"
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "यह GitHub URL साझा नहीं किया जा सकता।"
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "यह {boldName} का पूर्वावलोकन है — एक अंतर्निहित स्किल जो Open Knowledge के साथ आती है। यह केवल पढ़ने के लिए है।"
diff --git a/packages/app/src/locales/id/messages.json b/packages/app/src/locales/id/messages.json
index b1fbc133a..97c37bae1 100644
--- a/packages/app/src/locales/id/messages.json
+++ b/packages/app/src/locales/id/messages.json
@@ -4312,6 +4312,7 @@
],
"uVbUP8": ["Pengaturan…"],
"uY5Z7P": ["Permainan berakhir · tekan <0>Spasi</0> untuk main lagi"],
+ "uYZTcW": ["URL GitHub ini tidak dapat dibagikan."],
"u_lS4C": ["Kloning selesai — membuka proyek"],
"uaUc6t": ["Mulai ulang server"],
"ubMwcO": ["Sesi terminal berakhir (sinyal ", ["0"], ")."],
diff --git a/packages/app/src/locales/id/messages.po b/packages/app/src/locales/id/messages.po
index a17d4e8d7..f53b29ce7 100644
--- a/packages/app/src/locales/id/messages.po
+++ b/packages/app/src/locales/id/messages.po
@@ -13081,6 +13081,10 @@ msgstr "Folder ini bukan klona dari {expectedOwner}/{expectedRepo}. Pilih folder
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "Folder ini belum ada di GitHub. Tautannya tidak akan berfungsi sampai ia dikirim."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "URL GitHub ini tidak dapat dibagikan."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "Ini pratinjau {boldName} — keterampilan bawaan yang disertakan bersama Open Knowledge. Ia hanya-baca."
diff --git a/packages/app/src/locales/ko/messages.json b/packages/app/src/locales/ko/messages.json
index 38bdfb1e8..27de2a221 100644
--- a/packages/app/src/locales/ko/messages.json
+++ b/packages/app/src/locales/ko/messages.json
@@ -4112,6 +4112,7 @@
],
"uVbUP8": ["설정…"],
"uY5Z7P": ["게임 종료 · <0>스페이스</0>를 눌러 다시 시작"],
+ "uYZTcW": ["이 GitHub URL은 공유할 수 없습니다."],
"u_lS4C": ["클론 완료. 프로젝트 여는 중"],
"uaUc6t": ["서버 재시작"],
"ubMwcO": ["터미널 세션 종료(신호 ", ["0"], ")."],
diff --git a/packages/app/src/locales/ko/messages.po b/packages/app/src/locales/ko/messages.po
index 5749a8dea..45b6a161a 100644
--- a/packages/app/src/locales/ko/messages.po
+++ b/packages/app/src/locales/ko/messages.po
@@ -13085,6 +13085,10 @@ msgstr "이 폴더는 {expectedOwner}/{expectedRepo} 클론이 아닙니다. 다
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "이 폴더는 아직 GitHub에 없습니다. 푸시해야 링크가 작동합니다."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "이 GitHub URL은 공유할 수 없습니다."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "이것은 {boldName}의 미리보기입니다. Open Knowledge에 내장된 스킬이며 읽기 전용입니다."
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 5b8906847..1e33ed2ee 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -4280,6 +4280,7 @@
],
"uVbUP8": ["Śēţţĩńĝś…"],
"uY5Z7P": ["Ĝàḿē ōvēŕ · ƥŕēśś <0>Śƥàćē</0> ţō ƥĺàŷ àĝàĩń"],
+ "uYZTcW": ["Ţĥĩś ĜĩţĤũƀ ŨŔĹ ćàń'ţ ƀē śĥàŕēď."],
"u_lS4C": ["Ćĺōńē ćōḿƥĺēţē — ōƥēńĩńĝ ƥŕōĴēćţ"],
"uaUc6t": ["Ŕēśţàŕţ śēŕvēŕ"],
"ubMwcO": ["Ţĥē ţēŕḿĩńàĺ śēśśĩōń ēńďēď (śĩĝńàĺ ", ["0"], ")."],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index aebdc9f95..340b98a59 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -13081,6 +13081,10 @@ msgstr ""
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr ""
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr ""
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr ""
diff --git a/packages/app/src/locales/pt-BR/messages.json b/packages/app/src/locales/pt-BR/messages.json
index 1c4442f17..f5fb969a3 100644
--- a/packages/app/src/locales/pt-BR/messages.json
+++ b/packages/app/src/locales/pt-BR/messages.json
@@ -4836,6 +4836,7 @@
],
"uVbUP8": ["Configurações…"],
"uY5Z7P": ["Fim de jogo · pressione <0>Espaço</0> para jogar de novo"],
+ "uYZTcW": ["Não é possível compartilhar esta URL do GitHub."],
"u_lS4C": ["Clonagem concluída — abrindo o projeto"],
"uaUc6t": ["Reiniciar o servidor"],
"ubMwcO": ["A sessão de terminal terminou (sinal ", ["0"], ")."],
diff --git a/packages/app/src/locales/pt-BR/messages.po b/packages/app/src/locales/pt-BR/messages.po
index d3934ecc2..4b3325b0a 100644
--- a/packages/app/src/locales/pt-BR/messages.po
+++ b/packages/app/src/locales/pt-BR/messages.po
@@ -13081,6 +13081,10 @@ msgstr "Esta pasta não é um clone de {expectedOwner}/{expectedRepo}. Escolher
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "Esta pasta ainda não está no GitHub. O link não vai funcionar até ela ser enviada."
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "Não é possível compartilhar esta URL do GitHub."
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "Isto é uma pré-visualização de {boldName} — uma habilidade integrada que vem com o Open Knowledge. Ela é somente leitura."
diff --git a/packages/app/src/locales/ur/messages.json b/packages/app/src/locales/ur/messages.json
index 6797621bb..d18ec8a12 100644
--- a/packages/app/src/locales/ur/messages.json
+++ b/packages/app/src/locales/ur/messages.json
@@ -4356,6 +4356,7 @@
],
"uVbUP8": ["ترتیبات…"],
"uY5Z7P": ["کھیل ختم · دوبارہ کھیلنے کے لیے <0>اسپیس</0> دبائیں"],
+ "uYZTcW": ["اس GitHub URL کا اشتراک نہیں کیا جا سکتا۔"],
"u_lS4C": ["کلون مکمل — پروجیکٹ کھولا جا رہا ہے"],
"uaUc6t": ["سرور دوبارہ چلائیں"],
"ubMwcO": ["ٹرمینل کا سیشن ختم ہو گیا (سگنل ", ["0"], ")۔"],
diff --git a/packages/app/src/locales/ur/messages.po b/packages/app/src/locales/ur/messages.po
index 6aa0c0944..be73118cb 100644
--- a/packages/app/src/locales/ur/messages.po
+++ b/packages/app/src/locales/ur/messages.po
@@ -13085,6 +13085,10 @@ msgstr "یہ فولڈر {expectedOwner}/{expectedRepo} کا کلون نہیں۔
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "یہ فولڈر ابھی GitHub پر نہیں ہے۔ پُش ہونے تک لنک کام نہیں کرے گا۔"
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "اس GitHub URL کا اشتراک نہیں کیا جا سکتا۔"
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "یہ {boldName} کا پیش منظر ہے — ایک بلٹ اِن مہارت جو Open Knowledge کے ساتھ آتی ہے۔ یہ صرف پڑھنے کے لیے ہے۔"
diff --git a/packages/app/src/locales/zh-Hans/messages.json b/packages/app/src/locales/zh-Hans/messages.json
index 942b87d4f..b70092990 100644
--- a/packages/app/src/locales/zh-Hans/messages.json
+++ b/packages/app/src/locales/zh-Hans/messages.json
@@ -3780,6 +3780,7 @@
"uUiiyC": ["你没有推送到这个仓库的权限。「跟随」仍然可以让你的副本保持最新。"],
"uVbUP8": ["设置…"],
"uY5Z7P": ["游戏结束 · 按<0>空格</0>再玩一次"],
+ "uYZTcW": ["无法分享此 GitHub URL。"],
"u_lS4C": ["克隆完成——正在打开项目"],
"uaUc6t": ["重启服务器"],
"ubMwcO": ["终端会话已结束(信号 ", ["0"], ")。"],
diff --git a/packages/app/src/locales/zh-Hans/messages.po b/packages/app/src/locales/zh-Hans/messages.po
index 2c04c51ff..4ec4b6719 100644
--- a/packages/app/src/locales/zh-Hans/messages.po
+++ b/packages/app/src/locales/zh-Hans/messages.po
@@ -13085,6 +13085,10 @@ msgstr "此文件夹不是 {expectedOwner}/{expectedRepo} 的克隆。要换一
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "这个文件夹还不在 GitHub 上。在推送之前链接不会生效。"
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "无法分享此 GitHub URL。"
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "这是 {boldName} 的预览——一个随 Open Knowledge 一起提供的内置技能。它是只读的。"
diff --git a/packages/app/src/locales/zh-Hant/messages.json b/packages/app/src/locales/zh-Hant/messages.json
index 807b919fa..bbfed8f0f 100644
--- a/packages/app/src/locales/zh-Hant/messages.json
+++ b/packages/app/src/locales/zh-Hant/messages.json
@@ -3812,6 +3812,7 @@
"uUiiyC": ["你沒有推送到這個儲存庫的權限。「跟隨」仍然可以讓你的副本保持最新。"],
"uVbUP8": ["設定…"],
"uY5Z7P": ["遊戲結束 · 按<0>空白鍵</0>再玩一次"],
+ "uYZTcW": ["無法分享此 GitHub URL。"],
"u_lS4C": ["複製完成——正在開啟專案"],
"uaUc6t": ["重新啟動伺服器"],
"ubMwcO": ["終端機工作階段已結束(訊號 ", ["0"], ")。"],
diff --git a/packages/app/src/locales/zh-Hant/messages.po b/packages/app/src/locales/zh-Hant/messages.po
index fbde014a4..6c9e54e65 100644
--- a/packages/app/src/locales/zh-Hant/messages.po
+++ b/packages/app/src/locales/zh-Hant/messages.po
@@ -13085,6 +13085,10 @@ msgstr "這個資料夾不是 {expectedOwner}/{expectedRepo} 的複本。要換
msgid "This folder isn't on GitHub yet. The link won't work until it's pushed."
msgstr "這個資料夾還不在 GitHub 上。在推送之前連結不會生效。"
+#: src/lib/share/run-share-action.ts
+msgid "This GitHub URL can't be shared."
+msgstr "無法分享此 GitHub URL。"
+
#: src/components/SkillPreviewTab.tsx
msgid "This is a preview of {boldName} — a built-in skill shipped with Open Knowledge. It's read-only."
msgstr "這是 {boldName} 的預覽——一個隨 Open Knowledge 一起提供的內建技能。它是唯讀的。"
diff --git a/packages/core/src/schemas/api/share.test.ts b/packages/core/src/schemas/api/share.test.ts
index ab45cb77f..1923da00c 100644
--- a/packages/core/src/schemas/api/share.test.ts
+++ b/packages/core/src/schemas/api/share.test.ts
@@ -333,6 +333,12 @@ describe('ShareConstructUrlResponseSchema freshness field', () => {
expect(
ShareConstructUrlResponseSchema.safeParse({ ok: false, error: 'invalid-path' }).success,
).toBe(true);
+ expect(
+ ShareConstructUrlResponseSchema.safeParse({
+ ok: false,
+ error: 'unsupported-share-url',
+ }).success,
+ ).toBe(true);
// A freshness value is not an error code — adding `freshness` never
// widened the error enum.
expect(ShareConstructUrlResponseSchema.safeParse({ ok: false, error: 'stale' }).success).toBe(
diff --git a/packages/core/src/schemas/api/share.ts b/packages/core/src/schemas/api/share.ts
index cc830e5eb..b196c6206 100644
--- a/packages/core/src/schemas/api/share.ts
+++ b/packages/core/src/schemas/api/share.ts
@@ -9,9 +9,10 @@
* only (no `git ls-remote`) to keep the click-to-clipboard path under the
* 100ms p95 budget.
*
- * Wire contract returns HTTP 200 for BOTH the happy path and the five
+ * Wire contract returns HTTP 200 for BOTH the happy path and the six
* business-logic failures (no-remote / detached-head / branch-not-on-origin /
- * non-github-remote / invalid-path) — discriminated on `ok`. This is a
+ * non-github-remote / invalid-path / unsupported-share-url) — discriminated
+ * on `ok`. This is a
* deliberate departure from the RFC 9457 problem+json convention used
* elsewhere in the API: the share UI maps each failure code to a per-toast
* string, and routing those branches through 4xx would conflate them with
@@ -74,6 +75,8 @@ export type ShareConstructUrlRequest = z.infer<typeof ShareConstructUrlRequestSc
* directory path) traverses outside the project root or names the `.git/`
* subtree. An empty path is NOT invalid: it is a legitimate content-root
* folder share. The user-facing toast is generic.
+ * - `unsupported-share-url` — the otherwise accepted GitHub/GHES origin and
+ * target cannot be represented by the bounded, canonical v2 share codec.
*/
export const ShareConstructUrlErrorCodeSchema = z.enum([
'no-remote',
@@ -81,6 +84,7 @@ export const ShareConstructUrlErrorCodeSchema = z.enum([
'branch-not-on-origin',
'non-github-remote',
'invalid-path',
+ 'unsupported-share-url',
]) satisfies StandardSchemaV1;
export type ShareConstructUrlErrorCode = z.infer<typeof ShareConstructUrlErrorCodeSchema>;
diff --git a/packages/server/share-v2-smoke.ts b/packages/server/share-v2-smoke.ts
new file mode 100644
index 000000000..73b6209de
--- /dev/null
+++ b/packages/server/share-v2-smoke.ts
@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import {
+ decodeShareUrl,
+ type ShareConstructUrlResponse,
+ ShareConstructUrlResponseSchema,
+} from '@inkeep/open-knowledge-core';
+import type { EndpointRig } from './src/share/endpoint-http.test-helper.ts';
+
+type ShareSuccess = Extract<ShareConstructUrlResponse, { ok: true }>;
+
+const CONTENT_ROOT = 'knowledge base/handbook';
+const DOCUMENT_PATH = 'guides/getting started.md';
+const REPOSITORY_DOCUMENT_PATH = `${CONTENT_ROOT}/${DOCUMENT_PATH}`;
+const GITHUB_REPOSITORY = 'https://github.com/inkeep/open-knowledge';
+
+process.env.LOG_LEVEL ??= 'silent';
+const [{ bootEndpointServer }, { createGitTriangle }] = await Promise.all([
+ import('./src/share/endpoint-http.test-helper.ts'),
+ import('./src/share/git-fixture.test-helper.ts'),
+]);
+
+async function constructShare(port: number, body: unknown): Promise<ShareSuccess> {
+ const response = await fetch(`http://127.0.0.1:${port}/api/share/construct-url`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+ assert.equal(response.status, 200, `construct-url returned HTTP ${response.status}`);
+
+ const parsed = ShareConstructUrlResponseSchema.parse(await response.json());
+ if (!parsed.ok) assert.fail(`construct-url failed: ${parsed.error}`);
+ return parsed;
+}
+
+function tokenFromShareUrl(shareUrl: string): string {
+ const token = new URL(shareUrl).pathname.split('/').filter(Boolean).at(-1);
+ assert.ok(token, `share URL did not contain a token: ${shareUrl}`);
+ return token;
+}
+
+function printCase(
+ label: string,
+ result: ShareSuccess,
+ decoded: ReturnType<typeof decodeShareUrl>,
+): void {
+ console.log(`\n${label}`);
+ console.log(` token: v${decoded.version}`);
+ console.log(` source: ${result.sharedUrl}`);
+ console.log(` freshness: ${result.freshness ?? 'unavailable'}`);
+ if (decoded.version === 2) {
+ console.log(` root depth: ${decoded.contentRootDepth}`);
+ console.log(` target: ${JSON.stringify(decoded.target)}`);
+ }
+}
+
+const triangle = createGitTriangle();
+const rigs: EndpointRig[] = [];
+
+try {
+ triangle.seedAndPush(REPOSITORY_DOCUMENT_PATH, '# Getting started\n');
+ triangle.git(triangle.senderDir, ['remote', 'set-url', 'origin', `${GITHUB_REPOSITORY}.git`]);
+
+ const nestedRig = await bootEndpointServer({
+ projectDir: triangle.senderDir,
+ contentDir: join(triangle.senderDir, CONTENT_ROOT),
+ });
+ rigs.push(nestedRig);
+
+ const nestedDocument = await constructShare(nestedRig.port, {
+ kind: 'doc',
+ docPath: DOCUMENT_PATH,
+ });
+ const nestedDocumentDecoded = decodeShareUrl(tokenFromShareUrl(nestedDocument.shareUrl));
+ assert.deepEqual(nestedDocumentDecoded, {
+ version: 2,
+ sharedUrl: `${GITHUB_REPOSITORY}/blob/main/knowledge%20base/handbook/guides/getting%20started.md`,
+ contentRootDepth: 2,
+ source: {
+ host: 'github.com',
+ owner: 'inkeep',
+ repo: 'open-knowledge',
+ branch: 'main',
+ kind: 'doc',
+ targetSegments: ['knowledge base', 'handbook', 'guides', 'getting started.md'],
+ },
+ target: { kind: 'doc', docPath: DOCUMENT_PATH },
+ });
+ assert.equal(nestedDocument.freshness, 'current');
+
+ const nestedRoot = await constructShare(nestedRig.port, {
+ kind: 'folder',
+ folderPath: '',
+ });
+ const nestedRootDecoded = decodeShareUrl(tokenFromShareUrl(nestedRoot.shareUrl));
+ assert.deepEqual(nestedRootDecoded, {
+ version: 2,
+ sharedUrl: `${GITHUB_REPOSITORY}/tree/main/knowledge%20base/handbook`,
+ contentRootDepth: 2,
+ source: {
+ host: 'github.com',
+ owner: 'inkeep',
+ repo: 'open-knowledge',
+ branch: 'main',
+ kind: 'folder',
+ targetSegments: ['knowledge base', 'handbook'],
+ },
+ target: { kind: 'folder', folderPath: '' },
+ });
+ assert.equal(nestedRoot.freshness, 'current');
+
+ const rootRig = await bootEndpointServer({ projectDir: triangle.senderDir });
+ rigs.push(rootRig);
+
+ const rootDocument = await constructShare(rootRig.port, {
+ kind: 'doc',
+ docPath: REPOSITORY_DOCUMENT_PATH,
+ });
+ const rootDocumentDecoded = decodeShareUrl(tokenFromShareUrl(rootDocument.shareUrl));
+ assert.deepEqual(rootDocumentDecoded, {
+ version: 1,
+ sharedUrl: `${GITHUB_REPOSITORY}/blob/main/knowledge%20base/handbook/guides/getting%20started.md`,
+ });
+ assert.equal(rootDocument.freshness, 'current');
+
+ console.log('Share v2 smoke passed');
+ printCase('Nested content document', nestedDocument, nestedDocumentDecoded);
+ printCase('Nested content root', nestedRoot, nestedRootDecoded);
+ printCase('Repository-root compatibility', rootDocument, rootDocumentDecoded);
+} finally {
+ try {
+ await Promise.all(rigs.map((rig) => rig.cleanup()));
+ } finally {
+ triangle.cleanup();
+ }
+}
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 8521be968..08c8f6fd1 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -97,6 +97,7 @@ import {
type InlineAssetMediaKind,
InstallSkillRequestSchema,
InstallSkillSuccessSchema,
+ InvalidShareUrlError,
instantiateDoc,
isDetectedSkillInProject,
isFrontmatterSchemaAsset,
@@ -144,6 +145,7 @@ import {
type Principal,
PrincipalSuccessSchema,
type ProblemType,
+ parseCanonicalGitHubShareUrl,
parseFrontmatterRecord,
parseTemplateFile,
prependFrontmatter,
@@ -19879,10 +19881,10 @@ export function createApiExtension(
* the toast prompts the user to
* push, the retry succeeds.
*
- * Returns HTTP 200 with `{ok: false, error: code}` for the five business-
+ * Returns HTTP 200 with `{ok: false, error: code}` for the six business-
* logic failures (no-remote, detached-head, branch-not-on-origin,
- * non-github-remote, invalid-path) — DELIBERATE departure from RFC 9457
- * for these branches. The Share UI maps each code to a per-toast string;
+ * non-github-remote, invalid-path, unsupported-share-url) — DELIBERATE
+ * departure from RFC 9457 for these branches. The Share UI maps each code to a per-toast string;
* routing through 4xx would conflate share-flow outcomes with transport
* errors the client retries differently. Transport-class failures
* (loopback gate, payload-too-large, body-parse) still emit RFC 9457 via
@@ -19998,22 +20000,12 @@ export function createApiExtension(
if (contentRel === null) {
throw new Error('content dir is not contained within the project dir');
}
- // A non-root content.dir link keeps its historical shallow source URL:
- // the content-relative target is NOT prefixed with content.dir. Older
- // installed apps treat a received URL as the content-relative path
- // directly, and in-app receive navigation is already content-relative and
- // lands correctly — so prefixing content.dir into the source here would
- // double-count against the receiver. The tradeoff is that the raw
- // github.com link may point one level too shallow; warn so that mis-point
- // is observable in ops rather than silent.
- const sharingNonRootTarget =
- body.kind === 'doc' ? body.docPath !== '' : body.folderPath !== '';
- if (contentRel !== '' && sharingNonRootTarget) {
- getLogger('share').warn(
- { action: 'construct-url', kind: body.kind },
- '[share] content.dir != "." — non-root share URL omits the content.dir prefix; the github.com link may point at the wrong subtree. In-app receive navigation is content-relative and lands correctly.',
- );
- }
+ const repositorySharePath =
+ contentRel === ''
+ ? sharePath
+ : sharePath === ''
+ ? contentRel
+ : `${contentRel}/${sharePath}`;
let sharedUrl: string;
if (body.kind === 'doc') {
sharedUrl = buildGitHubBlobUrl(
@@ -20021,28 +20013,48 @@ export function createApiExtension(
origin.owner,
origin.repo,
branch,
- body.docPath,
+ repositorySharePath,
);
} else {
- // Folder ROOT (empty folderPath) maps to the content dir:
- // `tree/<branch>/<content.dir>`, degenerating to `tree/<branch>`
- // when `content.dir === '.'` (contentRel is '' then). Non-root folder
- // paths pass straight through.
- const treePath = body.folderPath === '' ? contentRel : body.folderPath;
- sharedUrl = buildGitHubTreeUrl(origin.host, origin.owner, origin.repo, branch, treePath);
- }
- const shareUrl = `${SHARE_BASE_URL}${encodeShareUrl(sharedUrl)}`;
- // Freshness probes the repo-relative path of the shared target: it
- // lives under content.dir, so join contentRel with the content-relative
- // share path. For the dominant content.dir === '.' case contentRel is
- // '' and this is just sharePath; an empty result is the content root.
- const freshnessPath =
- contentRel === ''
- ? sharePath
- : sharePath === ''
- ? contentRel
- : `${contentRel}/${sharePath}`;
- const freshness = await computeShareFreshness(projectDir, branch, freshnessPath, body.kind);
+ sharedUrl = buildGitHubTreeUrl(
+ origin.host,
+ origin.owner,
+ origin.repo,
+ branch,
+ repositorySharePath,
+ );
+ }
+ // Derive depth through the same canonical build + parse contract the
+ // reader uses. For valid contentRel values this count equals a raw
+ // slash split; the round-trip also validates the encoded URL before
+ // minting the token.
+ let shareUrl: string;
+ try {
+ const contentRootDepth =
+ contentRel === ''
+ ? 0
+ : parseCanonicalGitHubShareUrl(
+ buildGitHubTreeUrl(origin.host, origin.owner, origin.repo, branch, contentRel),
+ ).targetSegments.length;
+ shareUrl = `${SHARE_BASE_URL}${encodeShareUrl(sharedUrl, contentRootDepth)}`;
+ } catch (err) {
+ if (!(err instanceof InvalidShareUrlError)) throw err;
+ emitShareConstructUrlLog('unsupported-share-url', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'unsupported-share-url' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ const freshness = await computeShareFreshness(
+ projectDir,
+ branch,
+ repositorySharePath,
+ body.kind,
+ );
emitShareConstructUrlLog('ok', { branchExists: true, kind: body.kind, freshness });
successResponse(
res,
@@ -20052,9 +20064,8 @@ export function createApiExtension(
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
} catch (err) {
- // Defensive: every dependency (fs reads, regex, encode) is bounded,
- // but a future change might add a throwing branch and the structured
- // 200 contract above would otherwise leak the throw as an
+ // Defensive: a future dependency change might add a throwing branch,
+ // and the structured 200 contract above would otherwise leak the throw as an
// unhandled-rejection 500. Generic title — raw `err.message` could
// include FS paths.
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
diff --git a/packages/server/src/mcp/tools/output-schema-strictness.test.ts b/packages/server/src/mcp/tools/output-schema-strictness.test.ts
index d6dea1d50..e330ecce4 100644
--- a/packages/server/src/mcp/tools/output-schema-strictness.test.ts
+++ b/packages/server/src/mcp/tools/output-schema-strictness.test.ts
@@ -343,7 +343,7 @@ describe('move outputSchema admits the cross-level skill-move payloads (CORR-1)'
}
});
-describe('share_link outputSchema admits the freshness success payloads (S3)', () => {
+describe('share_link outputSchema admits emitted success and error payloads', () => {
// The `{text}`-only sweep can't catch a handler-emitted field the schema
// omits (it never sends `freshness`), so validate the EXACT success
// structuredContent — with and without freshness — against the compiled
@@ -398,11 +398,19 @@ describe('share_link outputSchema admits the freshness success payloads (S3)', (
freshness: 'empty',
text: "Git can't track this folder — it's empty or contains only ignored files. The link won't work until you add a tracked document.\n\nShare link for folder `hollow` on branch `main`:\nhttps://openknowledge.ai/d/enc",
};
+ const withUnsupportedUrlError = {
+ ok: false,
+ error: 'unsupported-share-url',
+ message:
+ 'The GitHub URL cannot be represented by the share-link format. Use a canonical DNS GitHub host and a shorter repository path.',
+ text: 'Error: The GitHub URL cannot be represented by the share-link format. Use a canonical DNS GitHub host and a shorter repository path.',
+ };
for (const [label, payload] of [
['success with freshness', withFreshness],
['success without freshness (happy-path passthrough)', withoutFreshness],
['success with the empty-folder verdict', withEmptyFreshness],
+ ['unsupported share URL error', withUnsupportedUrlError],
] as const) {
test(`${label} structuredContent validates against the compiled share_link schema`, () => {
const validator = new AjvJsonSchemaValidator();
diff --git a/packages/server/src/mcp/tools/share-link.test.ts b/packages/server/src/mcp/tools/share-link.test.ts
index 50ce0264f..1bff61a8e 100644
--- a/packages/server/src/mcp/tools/share-link.test.ts
+++ b/packages/server/src/mcp/tools/share-link.test.ts
@@ -6,7 +6,7 @@
* (`.mdx` → `.md` → directory) or pinned via `kind`. The six-case
* matrix lives in the "target resolution" describe block.
* - Trailing `.md`/`.mdx` normalization on doc paths.
- * - The five `ShareConstructUrlErrorCode` business-logic branches map to
+ * - The six `ShareConstructUrlErrorCode` business-logic branches map to
* distinct, agent-actionable messages. `no-remote` is the load-bearing
* one — it must direct the user at publishing (not run it).
* - Tool-local codes (`target-not-found`, `kind-mismatch`, `unknown`) are
@@ -133,10 +133,10 @@ afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
-function makeDeps(serverUrl: string | undefined): ShareLinkDeps {
+function makeDeps(serverUrl: string | undefined, config: Config = BASE_CONFIG): ShareLinkDeps {
return {
serverUrl,
- config: BASE_CONFIG,
+ config,
resolveCwd: async () => tmpDir,
};
}
@@ -329,6 +329,49 @@ describe('share_link — target resolution (FR9 matrix)', () => {
expect(seenRequests[0]?.body).toEqual({ kind: 'doc', docPath: 'guide.md' });
});
+ test('non-root content dir posts content-relative doc and folder paths', async () => {
+ const config = ConfigSchema.parse({ content: { dir: 'vault' } });
+ await mkdir(resolve(tmpDir, 'vault', 'guides'), { recursive: true });
+ await writeFile(resolve(tmpDir, 'vault', 'notes.md'), '# notes');
+ mockResponse = { status: 200, body: successBody() };
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, config));
+
+ const docResult = await getTool().handler({ path: 'notes', kind: 'doc' });
+ const folderResult = await getTool().handler({ path: 'guides', kind: 'folder' });
+
+ expect(docResult.isError).toBeUndefined();
+ expect(folderResult.isError).toBeUndefined();
+ expect(seenRequests.map(({ body }) => body)).toEqual([
+ { kind: 'doc', docPath: 'notes.md' },
+ { kind: 'folder', folderPath: 'guides' },
+ ]);
+ });
+
+ test('auto-probe (no kind) under a non-root content dir posts content-relative paths', async () => {
+ // The auto-probe branch resolves through its own return path, so the
+ // explicit-kind cases above do not cover it: a re-projection regression
+ // here would post `vault/...` and mint a link at the wrong subtree.
+ const config = ConfigSchema.parse({ content: { dir: 'vault' } });
+ await mkdir(resolve(tmpDir, 'vault', 'guides'), { recursive: true });
+ await writeFile(resolve(tmpDir, 'vault', 'notes.md'), '# notes');
+ mockResponse = { status: 200, body: successBody() };
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl, config));
+
+ const docResult = await getTool().handler({ path: 'notes' });
+ const folderResult = await getTool().handler({ path: 'guides' });
+
+ expect(docResult.isError).toBeUndefined();
+ expect(docResult.structuredContent).toMatchObject({ ok: true, resolvedKind: 'doc' });
+ expect(folderResult.isError).toBeUndefined();
+ expect(folderResult.structuredContent).toMatchObject({ ok: true, resolvedKind: 'folder' });
+ expect(seenRequests.map(({ body }) => body)).toEqual([
+ { kind: 'doc', docPath: 'notes.md' },
+ { kind: 'folder', folderPath: 'guides' },
+ ]);
+ });
+
test('rejects paths escaping the content root as target-not-found', async () => {
const { server, getTool } = createFakeServer();
register(server, makeDeps(baseUrl));
@@ -565,6 +608,22 @@ describe('share_link — business-logic errors', () => {
expect(message).not.toContain('Document');
});
+ test('unsupported-share-url: gives bounded recovery guidance', async () => {
+ await writeFile(resolve(tmpDir, 'page.md'), '# page');
+ mockResponse = { status: 200, body: { ok: false, error: 'unsupported-share-url' } };
+ const { server, getTool } = createFakeServer();
+ register(server, makeDeps(baseUrl));
+ const result = await getTool().handler({ path: 'page' });
+ expect(result.isError).toBe(true);
+ expect(result.structuredContent).toMatchObject({
+ ok: false,
+ error: 'unsupported-share-url',
+ });
+ const message = (result.structuredContent as { message: string }).message;
+ expect(message).toContain('canonical DNS GitHub host');
+ expect(message).toContain('shorter repository path');
+ });
+
test('branch-not-on-origin: message carries the stale-fetch recovery hint', async () => {
await writeFile(resolve(tmpDir, 'page.md'), '# page');
mockResponse = {
@@ -602,6 +661,7 @@ describe('share_link — message coverage', () => {
'branch-not-on-origin',
'non-github-remote',
'invalid-path',
+ 'unsupported-share-url',
] as const;
for (const code of SERVER_CODES) {
diff --git a/packages/server/src/mcp/tools/share-link.ts b/packages/server/src/mcp/tools/share-link.ts
index 784dc3fa3..87a905013 100644
--- a/packages/server/src/mcp/tools/share-link.ts
+++ b/packages/server/src/mcp/tools/share-link.ts
@@ -17,6 +17,7 @@ import { existsSync, statSync } from 'node:fs';
import { join } from 'node:path';
import {
type ShareConstructUrlErrorCode,
+ ShareConstructUrlErrorCodeSchema,
ShareConstructUrlResponseSchema,
type ShareFreshness,
ShareFreshnessSchema,
@@ -92,10 +93,10 @@ function freshnessWarning(freshness: ShareFreshness | undefined, kind: ShareKind
}
/**
- * Tool-local failure codes. The five `ShareConstructUrlErrorCode` server codes
+ * Tool-local failure codes. The six `ShareConstructUrlErrorCode` server codes
* flow through verbatim; `target-not-found`, `kind-mismatch`, and `unknown`
* are produced INLINE by this wrapper (not by `messageForShareError`, whose
- * `never`-guard must keep covering exactly the five server codes).
+ * `never`-guard must keep covering exactly the six server codes).
*
* `target-not-found` / `kind-mismatch` are distinct from the system-wide
* `urn:ok:error:doc-not-found` problem+json envelope — they live only in this
@@ -141,12 +142,14 @@ function messageForShareError(error: ShareConstructUrlErrorCode, branch?: string
return 'Origin is a non-GitHub remote (GitLab, Bitbucket, etc.). Share links require a GitHub remote (`github.com` or GitHub Enterprise Server).';
case 'invalid-path':
return 'The resolved share path is not shareable (escapes the project root or names the `.git` subtree). Pass a normal target path under the content directory.';
+ case 'unsupported-share-url':
+ return 'The GitHub URL cannot be represented by the share-link format. Use a canonical DNS GitHub host and a shorter repository path.';
default: {
// Exhaustiveness guard: adding a new variant to `ShareConstructUrlErrorCodeSchema`
// becomes a compile error here. The runtime fallback is informational only —
// TypeScript catches the divergence before we ship. Tool-local codes
// (target-not-found / kind-mismatch / unknown) are handled at their inline
- // call sites, never routed here, so the `never` guard stays over the five
+ // call sites, never routed here, so the `never` guard stays over the six
// server codes.
const _exhaustive: never = error;
return `Unknown share-construct-url error: ${String(_exhaustive)}`;
@@ -164,9 +167,9 @@ function isExistingDirectory(abs: string): boolean {
}
/**
- * Probe `<absBase>.mdx` then `.md`; return the project-relative path of the
+ * Probe `<absBase>.mdx` then `.md`; return the content-relative path of the
* first existing file, or `null` when neither exists / the file escapes the
- * project root.
+ * content root.
*
* Precedence matches `SUPPORTED_DOC_EXTENSIONS` in `doc-extensions.ts`:
* `.mdx` wins over `.md` when both exist (industry convention — `.mdx` is a
@@ -180,15 +183,15 @@ function isExistingDirectory(abs: string): boolean {
* Hocuspocus over HTTP. The existsSync probe is the out-of-process equivalent;
* it iterates `SUPPORTED_DOC_EXTENSIONS` directly so the precedence can't drift.
*/
-function resolveExistingDocPath(projectDir: string, absBase: string): string | null {
+function resolveExistingDocPath(contentDir: string, absBase: string): string | null {
for (const ext of SUPPORTED_DOC_EXTENSIONS) {
const absWithExt = `${absBase}${ext}`;
if (existsSync(absWithExt)) {
- const projectContained = resolveWithinRoot(projectDir, absWithExt);
- if (!projectContained.ok) return null;
+ const contentContained = resolveWithinRoot(contentDir, absWithExt);
+ if (!contentContained.ok) return null;
// `path.relative` returns `/`-separated paths on POSIX (the OK server's
// target platform per `path-safety.ts`), so no separator normalization needed.
- return projectContained.rel;
+ return contentContained.rel;
}
}
return null;
@@ -199,11 +202,9 @@ type ResolveShareTargetResult =
| { ok: false; code: 'target-not-found' | 'kind-mismatch' | 'invalid-path' };
/**
- * Resolve a caller-supplied `path` (+ optional `kind`) to the project-relative
+ * Resolve a caller-supplied `path` (+ optional `kind`) to the content-relative
* share path + kind the construct-url endpoint expects. Doc and folder share
- * the SAME containment + relative-to-content-root convention as the prior
- * doc-only resolver (`resolveWithinRoot` against `contentDir`, then re-project
- * the absolute hit against `projectDir`).
+ * the same containment + relative-to-content-root convention.
*
* Decision logic:
* - `path === ''` (root sentinel): valid ONLY for `kind === 'folder'` →
@@ -223,7 +224,6 @@ type ResolveShareTargetResult =
* `target-not-found`, mirroring the prior doc-only resolver's null-on-escape.
*/
function resolveShareTarget(
- projectDir: string,
contentDir: string,
path: string,
kind?: ShareKind,
@@ -243,7 +243,7 @@ function resolveShareTarget(
// as `path: 'notes'`. Folder probe uses the raw `contained.abs` (a directory
// named `foo.md` is its own literal path, not `foo`).
const docBase = contained.abs.replace(/\.(mdx|md)$/i, '');
- const docPath = resolveExistingDocPath(projectDir, docBase);
+ const docPath = resolveExistingDocPath(contentDir, docBase);
const dirExists = isExistingDirectory(contained.abs);
if (kind === 'doc') {
@@ -253,9 +253,7 @@ function resolveShareTarget(
}
if (kind === 'folder') {
if (dirExists) {
- const folderContained = resolveWithinRoot(projectDir, contained.abs);
- if (!folderContained.ok) return { ok: false, code: 'target-not-found' };
- return { ok: true, kind: 'folder', sharePath: folderContained.rel };
+ return { ok: true, kind: 'folder', sharePath: contained.rel };
}
if (docPath !== null) return { ok: false, code: 'kind-mismatch' };
return { ok: false, code: 'target-not-found' };
@@ -264,9 +262,7 @@ function resolveShareTarget(
// Auto-probe: first hit wins in `.mdx` → `.md` → directory order.
if (docPath !== null) return { ok: true, kind: 'doc', sharePath: docPath };
if (dirExists) {
- const folderContained = resolveWithinRoot(projectDir, contained.abs);
- if (!folderContained.ok) return { ok: false, code: 'target-not-found' };
- return { ok: true, kind: 'folder', sharePath: folderContained.rel };
+ return { ok: true, kind: 'folder', sharePath: contained.rel };
}
return { ok: false, code: 'target-not-found' };
}
@@ -303,11 +299,7 @@ const OutputSchema = outputSchemaWithText({
),
error: z
.enum([
- 'no-remote',
- 'detached-head',
- 'branch-not-on-origin',
- 'non-github-remote',
- 'invalid-path',
+ ...ShareConstructUrlErrorCodeSchema.options,
'target-not-found',
'kind-mismatch',
'unknown',
@@ -362,7 +354,7 @@ export function register(server: ServerInstance, deps: ShareLinkDeps): void {
if (!url) return textResult(HOCUSPOCUS_NOT_RUNNING_ERROR, true);
const contentDir = join(cwd, config.content.dir);
- const resolved = resolveShareTarget(cwd, contentDir, args.path, args.kind);
+ const resolved = resolveShareTarget(contentDir, args.path, args.kind);
if (!resolved.ok) {
let message: string;
if (resolved.code === 'kind-mismatch') {
@@ -383,7 +375,7 @@ export function register(server: ServerInstance, deps: ShareLinkDeps): void {
? { kind: 'doc' as const, docPath: resolved.sharePath }
: { kind: 'folder' as const, folderPath: resolved.sharePath };
- // construct-url returns HTTP 200 for BOTH the happy path AND the five
+ // construct-url returns HTTP 200 for BOTH the happy path AND the six
// business-logic failures, discriminated on body `ok`. Routing through
// `httpPost`/`normalizeResponse` would strip the body's `ok` field and
// force `ok: true` on every 200, so go direct and parse with the
diff --git a/packages/server/src/share/construct-url.test.ts b/packages/server/src/share/construct-url.test.ts
index 6320f37e6..597f04eba 100644
--- a/packages/server/src/share/construct-url.test.ts
+++ b/packages/server/src/share/construct-url.test.ts
@@ -22,7 +22,11 @@ interface TestRig {
async function bootRig(
initProject?: (projectDir: string) => void,
- opts?: { contentDirIsRoot?: boolean; contentDirEscapes?: boolean },
+ opts?: {
+ contentDirIsRoot?: boolean;
+ contentDirEscapes?: boolean;
+ contentDirRelative?: string;
+ },
): Promise<TestRig> {
const tmpRoot = await mkdtemp(join(tmpdir(), 'share-construct-url-'));
const projectDir = join(tmpRoot, 'project');
@@ -36,7 +40,7 @@ async function bootRig(
? join(tmpRoot, 'escaped-content')
: opts?.contentDirIsRoot
? projectDir
- : join(projectDir, 'content');
+ : join(projectDir, opts?.contentDirRelative ?? 'content');
mkdirSync(contentDir, { recursive: true });
initProject?.(projectDir);
@@ -129,7 +133,7 @@ describe('POST /api/share/construct-url', () => {
if (rig) await rig.cleanup();
});
- test('happy path: returns encoded share URL that round-trips via decodeShareUrl', async () => {
+ test('nested content dir mints a v2 document share with a content-relative target', async () => {
rig = await bootRig((projectDir) => {
seedRemoteAndHead(projectDir, {
head: 'ref: refs/heads/main\n',
@@ -142,15 +146,66 @@ describe('POST /api/share/construct-url', () => {
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
expect(json.branch).toBe('main');
- expect(json.sharedUrl).toBe('https://github.com/inkeep/open-knowledge/blob/main/docs/guide.md');
+ expect(json.sharedUrl).toBe(
+ 'https://github.com/inkeep/open-knowledge/blob/main/content/docs/guide.md',
+ );
expect(typeof json.shareUrl).toBe('string');
expect(json.shareUrl).toMatch(/^https:\/\/openknowledge\.ai\/d\/[A-Za-z0-9_-]+$/);
const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
const decoded = decodeShareUrl(encoded);
- expect(decoded.version).toBe(1);
- expect(decoded.sharedUrl).toBe(
- 'https://github.com/inkeep/open-knowledge/blob/main/docs/guide.md',
+ expect(decoded).toMatchObject({
+ version: 2,
+ sharedUrl: 'https://github.com/inkeep/open-knowledge/blob/main/content/docs/guide.md',
+ contentRootDepth: 1,
+ target: { kind: 'doc', docPath: 'docs/guide.md' },
+ });
+ });
+
+ test('repository-root content dir keeps document shares on v1', async () => {
+ rig = await bootRig(
+ (projectDir) => {
+ seedRemoteAndHead(projectDir, {
+ head: 'ref: refs/heads/main\n',
+ originUrl: 'https://github.com/inkeep/open-knowledge.git',
+ branchesOnOrigin: ['main'],
+ });
+ },
+ { contentDirIsRoot: true },
+ );
+ const res = await postConstructUrl(rig.port, { kind: 'doc', docPath: 'docs/guide.md' });
+ expect(res.status).toBe(200);
+ const json = (await res.json()) as Record<string, unknown>;
+ expect(json.sharedUrl).toBe('https://github.com/inkeep/open-knowledge/blob/main/docs/guide.md');
+ const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ expect(decodeShareUrl(encoded)).toEqual({
+ version: 1,
+ sharedUrl: 'https://github.com/inkeep/open-knowledge/blob/main/docs/guide.md',
+ });
+ });
+
+ test('a two-segment content dir mints content-root depth two', async () => {
+ rig = await bootRig(
+ (projectDir) => {
+ seedRemoteAndHead(projectDir, {
+ head: 'ref: refs/heads/main\n',
+ originUrl: 'https://github.com/inkeep/open-knowledge.git',
+ branchesOnOrigin: ['main'],
+ });
+ },
+ { contentDirRelative: 'knowledge base/handbook' },
+ );
+ const res = await postConstructUrl(rig.port, { kind: 'doc', docPath: 'start here.md' });
+ expect(res.status).toBe(200);
+ const json = (await res.json()) as Record<string, unknown>;
+ expect(json.sharedUrl).toBe(
+ 'https://github.com/inkeep/open-knowledge/blob/main/knowledge%20base/handbook/start%20here.md',
);
+ const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ expect(decodeShareUrl(encoded)).toMatchObject({
+ version: 2,
+ contentRootDepth: 2,
+ target: { kind: 'doc', docPath: 'start here.md' },
+ });
});
test('no-remote: project has no origin section', async () => {
@@ -230,7 +285,13 @@ describe('POST /api/share/construct-url', () => {
expect(res.status).toBe(200);
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
- expect(json.sharedUrl).toBe('https://ghes.acme.test/team/notes/blob/main/a.md');
+ expect(json.sharedUrl).toBe('https://ghes.acme.test/team/notes/blob/main/content/a.md');
+ const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ expect(decodeShareUrl(encoded)).toMatchObject({
+ version: 2,
+ contentRootDepth: 1,
+ target: { kind: 'doc', docPath: 'a.md' },
+ });
});
test('invalid-path: rejects .. segment', async () => {
@@ -289,7 +350,7 @@ describe('POST /api/share/construct-url', () => {
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
expect(json.sharedUrl).toBe(
- `https://github.com/inkeep/open-knowledge/blob/main/${encodeURIComponent('Q4 OKRs — Marketing.md').replace(/^/, 'docs/')}`,
+ `https://github.com/inkeep/open-knowledge/blob/main/content/${encodeURIComponent('Q4 OKRs — Marketing.md').replace(/^/, 'docs/')}`,
);
const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
const decoded = decodeShareUrl(encoded);
@@ -301,7 +362,12 @@ describe('POST /api/share/construct-url', () => {
.slice(5)
.map((s) => decodeURIComponent(s))
.join('/');
- expect(decodedDocPath).toBe(docPath);
+ expect(decodedDocPath).toBe(`content/${docPath}`);
+ expect(decoded).toMatchObject({
+ version: 2,
+ contentRootDepth: 1,
+ target: { kind: 'doc', docPath },
+ });
});
test('happy path: branch with slash via loose ref encodes as single segment', async () => {
@@ -318,7 +384,7 @@ describe('POST /api/share/construct-url', () => {
expect(json.ok).toBe(true);
expect(json.branch).toBe('feat/sharing-virality-flow');
expect(json.sharedUrl).toBe(
- 'https://github.com/inkeep/open-knowledge/blob/feat%2Fsharing-virality-flow/docs/guide.md',
+ 'https://github.com/inkeep/open-knowledge/blob/feat%2Fsharing-virality-flow/content/docs/guide.md',
);
const sharedUrl = new URL(json.sharedUrl as string);
const segments = sharedUrl.pathname.split('/').filter(Boolean);
@@ -388,12 +454,19 @@ describe('POST /api/share/construct-url', () => {
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
expect(json.branch).toBe('main');
- expect(json.sharedUrl).toBe('https://github.com/inkeep/open-knowledge/tree/main/docs/guides');
+ expect(json.sharedUrl).toBe(
+ 'https://github.com/inkeep/open-knowledge/tree/main/content/docs/guides',
+ );
const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
const decoded = decodeShareUrl(encoded);
expect(decoded.sharedUrl).toBe(
- 'https://github.com/inkeep/open-knowledge/tree/main/docs/guides',
+ 'https://github.com/inkeep/open-knowledge/tree/main/content/docs/guides',
);
+ expect(decoded).toMatchObject({
+ version: 2,
+ contentRootDepth: 1,
+ target: { kind: 'folder', folderPath: 'docs/guides' },
+ });
});
test('folder ROOT (folderPath: "") with content.dir === "." degenerates to tree/<branch>', async () => {
@@ -412,6 +485,8 @@ describe('POST /api/share/construct-url', () => {
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
expect(json.sharedUrl).toBe('https://github.com/inkeep/open-knowledge/tree/main');
+ const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ expect(decodeShareUrl(encoded).version).toBe(1);
});
test('folder ROOT (folderPath: "") with content.dir subdir maps to tree/<branch>/<content.dir>', async () => {
@@ -428,6 +503,12 @@ describe('POST /api/share/construct-url', () => {
const json = (await res.json()) as Record<string, unknown>;
expect(json.ok).toBe(true);
expect(json.sharedUrl).toBe('https://github.com/inkeep/open-knowledge/tree/main/content');
+ const encoded = (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ expect(decodeShareUrl(encoded)).toMatchObject({
+ version: 2,
+ contentRootDepth: 1,
+ target: { kind: 'folder', folderPath: '' },
+ });
});
test('folder ROOT (folderPath: "") with contentDir escaping projectDir fails loud (500), not a repo-root link', async () => {
diff --git a/packages/server/src/share/endpoint-real-git.test.ts b/packages/server/src/share/endpoint-real-git.test.ts
index 08d20d4f8..d3dc10beb 100644
--- a/packages/server/src/share/endpoint-real-git.test.ts
+++ b/packages/server/src/share/endpoint-real-git.test.ts
@@ -11,6 +11,8 @@
import { createServer as createHttpServer } from 'node:http';
import type { AddressInfo, Socket } from 'node:net';
+import { join } from 'node:path';
+import { decodeShareUrl } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test } from 'vitest';
import { bootEndpointServer, type EndpointRig } from './endpoint-http.test-helper.ts';
import { createGitTriangle, type GitTriangle } from './git-fixture.test-helper.ts';
@@ -269,6 +271,116 @@ describe('POST /api/share/construct-url (freshness computed through the endpoint
});
});
+describe('POST /api/share/construct-url (v2 minting through the endpoint)', () => {
+ function shareToken(json: Record<string, unknown>): string {
+ return (json.shareUrl as string).replace('https://openknowledge.ai/d/', '');
+ }
+
+ test('a nested content root mints v2 with current freshness and the reader-decodable source', async () => {
+ const t = newTriangle();
+ t.seedAndPush('knowledge base/handbook/guides/getting started.md', '# Getting started\n');
+ repointOriginAtGitHub(t);
+
+ rig = await bootEndpointServer({
+ projectDir: t.senderDir,
+ contentDir: join(t.senderDir, 'knowledge base/handbook'),
+ });
+ const res = await postConstructUrl(rig.port, {
+ kind: 'doc',
+ docPath: 'guides/getting started.md',
+ });
+
+ expect(res.status).toBe(200);
+ const json = (await res.json()) as Record<string, unknown>;
+ // `current` needs real pushed blobs — the seeded-`.git` unit rig cannot
+ // produce it — so the join of content root and content-relative target that
+ // feeds the freshness probe is pinned here, at the tier where a wrong join
+ // misreports the verdict for every nested-content share.
+ expect(json).toMatchObject({ ok: true, freshness: 'current' });
+ expect(decodeShareUrl(shareToken(json))).toEqual({
+ version: 2,
+ sharedUrl:
+ 'https://github.com/o/r/blob/main/knowledge%20base/handbook/guides/getting%20started.md',
+ contentRootDepth: 2,
+ source: {
+ host: 'github.com',
+ owner: 'o',
+ repo: 'r',
+ branch: 'main',
+ kind: 'doc',
+ targetSegments: ['knowledge base', 'handbook', 'guides', 'getting started.md'],
+ },
+ target: { kind: 'doc', docPath: 'guides/getting started.md' },
+ });
+ });
+
+ test('a nested content root returns a business error when its origin cannot be encoded as v2', async () => {
+ const t = newTriangle();
+ t.seedAndPush('knowledge/doc.md', '# Document\n');
+ t.git(t.senderDir, ['remote', 'set-url', 'origin', 'https://127.0.0.1/o/r.git']);
+
+ rig = await bootEndpointServer({
+ projectDir: t.senderDir,
+ contentDir: join(t.senderDir, 'knowledge'),
+ });
+ const res = await postConstructUrl(rig.port, { kind: 'doc', docPath: 'doc.md' });
+
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ ok: false, error: 'unsupported-share-url' });
+ });
+
+ test('the nested content-root folder share is current and decodes to the root target', async () => {
+ const t = newTriangle();
+ t.seedAndPush('knowledge base/handbook/guides/getting started.md', '# Getting started\n');
+ repointOriginAtGitHub(t);
+
+ rig = await bootEndpointServer({
+ projectDir: t.senderDir,
+ contentDir: join(t.senderDir, 'knowledge base/handbook'),
+ });
+ const res = await postConstructUrl(rig.port, { kind: 'folder', folderPath: '' });
+
+ expect(res.status).toBe(200);
+ const json = (await res.json()) as Record<string, unknown>;
+ expect(json).toMatchObject({ ok: true, freshness: 'current' });
+ expect(decodeShareUrl(shareToken(json))).toEqual({
+ version: 2,
+ sharedUrl: 'https://github.com/o/r/tree/main/knowledge%20base/handbook',
+ contentRootDepth: 2,
+ source: {
+ host: 'github.com',
+ owner: 'o',
+ repo: 'r',
+ branch: 'main',
+ kind: 'folder',
+ targetSegments: ['knowledge base', 'handbook'],
+ },
+ target: { kind: 'folder', folderPath: '' },
+ });
+ });
+
+ test('a repository-root content dir still mints v1 for the same pushed target', async () => {
+ const t = newTriangle();
+ t.seedAndPush('knowledge base/handbook/guides/getting started.md', '# Getting started\n');
+ repointOriginAtGitHub(t);
+
+ rig = await bootEndpointServer({ projectDir: t.senderDir });
+ const res = await postConstructUrl(rig.port, {
+ kind: 'doc',
+ docPath: 'knowledge base/handbook/guides/getting started.md',
+ });
+
+ expect(res.status).toBe(200);
+ const json = (await res.json()) as Record<string, unknown>;
+ expect(json).toMatchObject({ ok: true, freshness: 'current' });
+ expect(decodeShareUrl(shareToken(json))).toEqual({
+ version: 1,
+ sharedUrl:
+ 'https://github.com/o/r/blob/main/knowledge%20base/handbook/guides/getting%20started.md',
+ });
+ });
+});
+
describe('target-status fetch timeout', () => {
test('a hanging credentialed fetch is bounded by the block timeout and degrades to unknown', async () => {
const t = newTriangle();