@bevel-software/platform-core-backend 0.4.1 → 0.5.1

package/dist/modules/settings/setup.routes.d.ts

@@ -0,0 +1,49 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { DeploymentSettingsService } from './deployment-settings.service.js';
+import '../auth/auth.middleware.js';
+/**
+ * First-run setup — the deployment's own configuration, for the things that
+ * used to be environment-only.
+ *
+ * WHY THESE ROUTES ARE AUTHENTICATED BUT NOT KB-DEPENDENT: the whole point is
+ * to be reachable on a deployment that has no knowledge base yet. That works
+ * because the bootstrap admin (`ADMIN_EMAIL`) is recognised without consulting
+ * `roles.yaml` — `AdminAccessService` short-circuits on it before any clone is
+ * attempted — so the one person who can finish setup can always sign in, and
+ * nobody else is let near it.
+ */
+export declare function createSetupRoutes(settings: DeploymentSettingsService, adminAccess: IAdminAccessService): express.Router;
+/**
+ * Whether the STORED configuration answers everything the deployment needs.
+ *
+ * The KB needs a URL and a token — the username and the directory name both
+ * have working defaults, so neither can block a start. The branch model has no
+ * default ON PURPOSE: guessing `main` would silently point a deployment at the
+ * wrong branch and let the protected-branch guards apply to nothing, which is
+ * worse than asking.
+ *
+ * SSO is deliberately absent. It is configuration, not a prerequisite — a
+ * deployment signs in perfectly well without it, and gating on it would lock
+ * an admin out of the screen where they would set it up.
+ */
+export declare function settingsAnswered(settings: DeploymentSettingsService): boolean;
+/**
+ * Whether THIS PROCESS can actually serve — which is not the same question,
+ * and conflating them opened the gate onto a broken app.
+ *
+ * The branch model is applied once, during boot: services take `DEFAULT_BRANCH`
+ * at construction and the browser is served it before it renders. Saving it
+ * therefore answers the question without changing the answer this process
+ * holds — so a deployment configured through the setup screen reported itself
+ * complete while every workspace call still failed with
+ * `Invalid branch name ""`.
+ *
+ * Requiring the model to be IN EFFECT keeps the gate shut until the restart
+ * that puts it there. {@link awaitingRestart} is what tells the screen to ask
+ * for one rather than claim a field is missing.
+ */
+export declare function isComplete(settings: DeploymentSettingsService): boolean;
+/** Answered, but not yet in effect: everything is stored, the process is stale. */
+export declare function awaitingRestart(settings: DeploymentSettingsService): boolean;
+//# sourceMappingURL=setup.routes.d.ts.map

package/dist/modules/settings/setup.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/settings/setup.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EACL,yBAAyB,EAG1B,MAAM,kCAAkC,CAAC;AAM1C,OAAO,4BAA4B,CAAC;AAIpC;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,yBAAyB,EACnC,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,MAAM,CAqNhB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAQ7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAEvE;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAE5E"}

package/dist/modules/settings/setup.routes.js

@@ -0,0 +1,292 @@
+import express from 'express';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SettingsValidationError, validateHttpsRemote, } from './deployment-settings.service.js';
+import { configureBranchModel, isBranchModelConfigured, validateBranchModel, } from '@bevel-software/platform-shared';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+const execFileAsync = promisify(execFile);
+/**
+ * First-run setup — the deployment's own configuration, for the things that
+ * used to be environment-only.
+ *
+ * WHY THESE ROUTES ARE AUTHENTICATED BUT NOT KB-DEPENDENT: the whole point is
+ * to be reachable on a deployment that has no knowledge base yet. That works
+ * because the bootstrap admin (`ADMIN_EMAIL`) is recognised without consulting
+ * `roles.yaml` — `AdminAccessService` short-circuits on it before any clone is
+ * attempted — so the one person who can finish setup can always sign in, and
+ * nobody else is let near it.
+ */
+export function createSetupRoutes(settings, adminAccess) {
+    const router = express.Router();
+    const requireAdmin = async (req, res, next) => {
+        if (!(await adminAccess.isAdmin(req.userEmail))) {
+            res.status(403).json({ error: 'Admins only' });
+            return;
+        }
+        next();
+    };
+    /**
+     * Whether the deployment is usable, and — for an admin — what is missing.
+     *
+     * Deliberately readable by ANY signed-in user, because everyone needs the
+     * answer: a non-admin who arrives mid-setup gets told the deployment is
+     * still being configured instead of a broken file tree. Only the admin
+     * branch carries the settings themselves, and no branch ever carries a
+     * secret's value.
+     */
+    router.get('/setup/status', async (req, res) => {
+        const complete = isComplete(settings);
+        if (!(await adminAccess.isAdmin(req.userEmail))) {
+            res.json({ complete, isAdmin: false });
+            return;
+        }
+        res.json({
+            complete,
+            awaitingRestart: awaitingRestart(settings),
+            isAdmin: true,
+            settings: settings.describe(),
+        });
+    });
+    /**
+     * Save settings. Validated and written as ONE batch — a repository URL
+     * stored without the token that reads it is a deployment that fails at its
+     * first clone, so a partial write is never better than none.
+     */
+    router.post('/setup/settings', requireAdmin, async (req, res) => {
+        const body = (req.body ?? {});
+        const entries = {};
+        for (const [key, value] of Object.entries(body.settings ?? {})) {
+            if (typeof value !== 'string') {
+                res.status(400).json({ error: `"${key}" must be a string.` });
+                return;
+            }
+            entries[key] = value;
+        }
+        try {
+            const { restartRequired } = await settings.save(entries, req.userId ?? null);
+            /**
+             * Apply the branch model to THIS process, so pressing Save finishes
+             * setup instead of asking for a restart.
+             *
+             * Only when it was not already configured — reconfiguring a live
+             * deployment mid-flight would swap the branches out from under sessions
+             * that are using them, which is a different and much less welcome
+             * feature. Going from "none" to "some" has nobody to disturb: the app is
+             * gated shut until exactly this moment.
+             *
+             * The services that need it read it when they use it rather than
+             * capturing it at construction, which is what makes applying it here
+             * enough.
+             */
+            if (!isBranchModelConfigured()) {
+                const model = {
+                    defaultBranch: settings.resolve('defaultBranch'),
+                    protectedBranches: settings.resolve('protectedBranches'),
+                };
+                if (!validateBranchModel(model))
+                    configureBranchModel(model);
+            }
+            res.json({
+                ok: true,
+                restartRequired,
+                complete: isComplete(settings),
+                awaitingRestart: awaitingRestart(settings),
+                settings: settings.describe(),
+            });
+        }
+        catch (err) {
+            if (err instanceof SettingsValidationError) {
+                res.status(400).json({ error: 'Some settings need fixing.', problems: err.problems });
+                return;
+            }
+            // Logged in full, returned generic: a driver message here would hand back
+            // the schema or the connection string.
+            console.error('[setup] save failed:', err instanceof Error ? err.message : String(err));
+            res.status(500).json({ error: 'Could not save these settings.' });
+        }
+    });
+    /**
+     * Try the credentials against the real remote, BEFORE anything is saved.
+     *
+     * This is the reason the screen is worth more than the environment variables
+     * it replaces. `ls-remote` is the cheapest operation that proves all three
+     * values at once — the URL resolves, the token authenticates, and the
+     * username is the one this host expects — and it answers in a second instead
+     * of surfacing as a failed clone at some later, unrelated moment.
+     *
+     * Values are taken from the request when supplied so an admin can test what
+     * they typed rather than what is stored, and fall back to what is in effect
+     * (which is how "test the token I saved last week" works).
+     */
+    router.post('/setup/test-connection', requireAdmin, async (req, res) => {
+        const body = (req.body ?? {});
+        const supplied = (key) => {
+            const value = body[key];
+            return typeof value === 'string' && value.trim() ? value.trim() : null;
+        };
+        const url = supplied('kbRepoUrl') ?? settings.resolve('kbRepoUrl');
+        // Unlike the token, the username is not a secret and carries a default —
+        // it is which name the host expects beside the token, not a credential.
+        const username = supplied('gitUsername') ?? (settings.resolve('gitUsername') || 'x-access-token');
+        if (!url) {
+            res.status(400).json({ ok: false, error: 'Enter the repository URL first.' });
+            return;
+        }
+        /**
+         * THE CONFIGURED TOKEN ONLY EVER GOES TO THE CONFIGURED REPOSITORY.
+         *
+         * The stored token is deliberately unreadable — `describe()` omits it, so
+         * an admin can replace it but never see it. Falling back to it for whatever
+         * URL the request names would hand that value straight back: point the test
+         * at a host you control, read it out of the request. Admin-gated, but the
+         * whole point of not returning it is that being an admin is not the same as
+         * being allowed to hold it.
+         *
+         * So a request that names a DIFFERENT repository has to bring its own
+         * credential. Testing what is already configured — the "does the token I
+         * saved last week still work?" case — is unaffected.
+         */
+        const suppliedToken = supplied('gitToken');
+        const testingConfiguredRepo = url === settings.resolve('kbRepoUrl');
+        if (!suppliedToken && !testingConfiguredRepo) {
+            res.status(400).json({
+                ok: false,
+                error: 'Enter the access token for that repository — the saved one is only used with the repository it was saved for.',
+            });
+            return;
+        }
+        const token = suppliedToken ?? (testingConfiguredRepo ? settings.resolve('gitToken') : '');
+        // The SAME rule the setting is validated by, applied before the value ever
+        // reaches git. Without it this endpoint is argument injection: a value
+        // beginning `--upload-pack=` makes git run a command of the caller's
+        // choosing, and `ext::sh -c …` is a transport whose entire purpose is to
+        // execute one. Both are admin-only, but "admin" is not "may run arbitrary
+        // commands as the server process".
+        const urlProblem = validateHttpsRemote(url);
+        if (urlProblem) {
+            res.status(400).json({ ok: false, error: urlProblem });
+            return;
+        }
+        if (!/^[A-Za-z0-9._-]+$/.test(username)) {
+            // Interpolated into the credential-helper snippet below.
+            res.status(400).json({ ok: false, error: 'The username contains unsupported characters.' });
+            return;
+        }
+        try {
+            // The helper reads the token from the environment at call time, so it
+            // never appears in argv (and so never in a process listing or a crash
+            // dump). Same shape the real clone uses.
+            const args = ['-c', 'credential.helper=', ...(token
+                    ? ['-c', `credential.helper=!f() { echo "username=${username}"; echo "password=$BEVEL_TEST_TOKEN"; }; f`]
+                    : []),
+                // `--end-of-options` on top of the validation above: belt and braces,
+                // so nothing that arrives here can ever be read as a flag.
+                'ls-remote', '--heads', '--end-of-options', url];
+            const { stdout } = await execFileAsync('git', args, {
+                timeout: 20_000,
+                env: {
+                    ...process.env,
+                    BEVEL_TEST_TOKEN: token,
+                    // Never let git stop for a prompt: without this a bad credential
+                    // hangs the request until the timeout instead of failing.
+                    GIT_TERMINAL_PROMPT: '0',
+                    GIT_ASKPASS: 'echo',
+                },
+            });
+            const lines = stdout.split('\n');
+            // `<sha>\trefs/heads/<name>` — tag refs and the bare HEAD row are not
+            // branches, so they are filtered rather than sliced blindly.
+            const branches = lines
+                .filter((line) => !line.startsWith('ref:'))
+                .map((line) => line.split('\t')[1]?.trim())
+                .filter((ref) => !!ref && ref.startsWith('refs/heads/'))
+                .map((ref) => ref.slice('refs/heads/'.length));
+            // `ref: refs/heads/<name>\tHEAD` — what the remote calls its own trunk.
+            const defaultBranch = lines
+                .find((line) => line.startsWith('ref:') && line.trimEnd().endsWith('HEAD'))
+                ?.slice('ref: refs/heads/'.length)
+                .split('\t')[0]
+                ?.trim() || null;
+            res.json({
+                ok: true,
+                // An EMPTY repository is a success, not a failure — seeding one is a
+                // supported path, and saying "no branches yet" beats an error that
+                // reads like the credentials are wrong.
+                empty: branches.length === 0,
+                branches,
+                defaultBranch,
+            });
+        }
+        catch (err) {
+            res.status(200).json({ ok: false, error: explainGitFailure(err, token) });
+        }
+    });
+    return router;
+}
+/**
+ * Whether the STORED configuration answers everything the deployment needs.
+ *
+ * The KB needs a URL and a token — the username and the directory name both
+ * have working defaults, so neither can block a start. The branch model has no
+ * default ON PURPOSE: guessing `main` would silently point a deployment at the
+ * wrong branch and let the protected-branch guards apply to nothing, which is
+ * worse than asking.
+ *
+ * SSO is deliberately absent. It is configuration, not a prerequisite — a
+ * deployment signs in perfectly well without it, and gating on it would lock
+ * an admin out of the screen where they would set it up.
+ */
+export function settingsAnswered(settings) {
+    const kb = Boolean(settings.resolve('kbRepoUrl') && settings.resolve('gitToken'));
+    const branches = validateBranchModel({
+        defaultBranch: settings.resolve('defaultBranch'),
+        protectedBranches: settings.resolve('protectedBranches'),
+    }) === null;
+    return kb && branches;
+}
+/**
+ * Whether THIS PROCESS can actually serve — which is not the same question,
+ * and conflating them opened the gate onto a broken app.
+ *
+ * The branch model is applied once, during boot: services take `DEFAULT_BRANCH`
+ * at construction and the browser is served it before it renders. Saving it
+ * therefore answers the question without changing the answer this process
+ * holds — so a deployment configured through the setup screen reported itself
+ * complete while every workspace call still failed with
+ * `Invalid branch name ""`.
+ *
+ * Requiring the model to be IN EFFECT keeps the gate shut until the restart
+ * that puts it there. {@link awaitingRestart} is what tells the screen to ask
+ * for one rather than claim a field is missing.
+ */
+export function isComplete(settings) {
+    return settingsAnswered(settings) && isBranchModelConfigured();
+}
+/** Answered, but not yet in effect: everything is stored, the process is stale. */
+export function awaitingRestart(settings) {
+    return settingsAnswered(settings) && !isBranchModelConfigured();
+}
+/**
+ * Turn git's stderr into something an admin can act on. Deliberately narrow:
+ * the raw text is echoed only when it matches nothing known, and the token is
+ * scrubbed from it first — `ls-remote` failures have been known to quote the
+ * credential back.
+ */
+function explainGitFailure(err, token) {
+    const raw = err instanceof Error ? `${err.message}` : String(err);
+    const text = token ? raw.replaceAll(token, '***') : raw;
+    if (/timed out|ETIMEDOUT/i.test(text)) {
+        return 'The host did not answer in time. Check the URL, and that this server can reach it.';
+    }
+    if (/Authentication failed|could not read Username|invalid credentials|403/i.test(text)) {
+        return 'The host rejected those credentials. Check the token, and that the username matches the host (GitHub x-access-token, GitLab oauth2, Bitbucket x-token-auth).';
+    }
+    if (/not found|repository .* does not exist|404/i.test(text)) {
+        return 'No repository at that URL — or the token cannot see it.';
+    }
+    if (/could not resolve host|unable to access|SSL|certificate/i.test(text)) {
+        return 'Could not reach that host from this server. Check the URL and any network egress rules.';
+    }
+    return text.split('\n').slice(0, 3).join(' ').slice(0, 400);
+}
+//# sourceMappingURL=setup.routes.js.map

package/dist/modules/settings/setup.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.routes.js","sourceRoot":"","sources":["../../../src/modules/settings/setup.routes.ts"],"names":[],"mappings":"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"}

package/dist/modules/skills/index.d.ts

@@ -1,5 +1,6 @@
 export { SkillService } from './skills.service.js';
+export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
-export type { ISkillService, Skill, SkillSummary, SkillFileContent, GetSkillResult, } from './skills.contract.js';
+export type { ISkillService, IPendingSkillService, Skill, SkillSummary, SkillFileContent, PendingSkill, GetSkillResult, } from './skills.contract.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/skills/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,GACf,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,sBAAsB,CAAC"}

package/dist/modules/skills/index.js

@@ -1,4 +1,5 @@
 export { SkillService } from './skills.service.js';
+export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
 //# sourceMappingURL=index.js.map

package/dist/modules/skills/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/skills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/modules/skills/pending-skills.service.d.ts

@@ -0,0 +1,40 @@
+import { type IWorkflowService } from '@bevel-software/platform-shared';
+import { type WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IPendingSkillService, ISkillService, PendingSkill } from './skills.contract.js';
+/**
+ * Skills that exist only on an open change request — proposed, not released.
+ *
+ * The catalog (`SkillService`) is pinned to the default branch, which is the
+ * right answer for everything that LOADS a skill and the wrong one for the
+ * person who just proposed it: a change request that ADDS a skill folder has
+ * nothing on the default branch to hang itself off, so until it merged the
+ * proposal was invisible to its author and to the people who had to approve it.
+ * This service is that missing half, and it is deliberately a separate surface
+ * rather than a widening of the catalog — an unapproved skill must never become
+ * loadable just because it became visible.
+ *
+ * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
+ * whoever could approve it. "Could approve it" is not re-stated here as a
+ * group-admin check — it is `canWrite` on the SKILL.md the request would
+ * create. The new folder carries no `access.md` of its own, so that verdict
+ * inherits from the group folder, which IS the group's admin; asking the access
+ * tree keeps this surface and the merge gate answering with one voice, and it
+ * keeps working for skills nested in a category subfolder that carries rules of
+ * its own.
+ *
+ * Everything degrades to "nothing pending" rather than throwing: this hangs off
+ * the library's list load, and a review surface that cannot answer must not
+ * take the shelf down with it.
+ */
+export declare class PendingSkillsService implements IPendingSkillService {
+    private readonly workspaceService;
+    private readonly accessControl;
+    private readonly skillService;
+    private readonly workflow;
+    constructor(workspaceService: WorkspaceService, accessControl: IAccessControl, skillService: ISkillService, workflow: IWorkflowService);
+    listPendingSkills(userEmail: string): Promise<PendingSkill[]>;
+    /** The file at a branch, or null when it is absent/unreadable there. */
+    private readAt;
+}
+//# sourceMappingURL=pending-skills.service.d.ts.map

package/dist/modules/skills/pending-skills.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-skills.service.d.ts","sourceRoot":"","sources":["../../../src/modules/skills/pending-skills.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAI5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAI9F;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,oBAAqB,YAAW,oBAAoB;IAE7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAHR,gBAAgB,EAAE,gBAAgB,EAClC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,aAAa,EAC3B,QAAQ,EAAE,gBAAgB;IAGvC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqFnE,wEAAwE;YAC1D,MAAM;CAWrB"}

package/dist/modules/skills/pending-skills.service.js

@@ -0,0 +1,147 @@
+import { DEFAULT_BRANCH, GROUPS_DIR, } from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { hashEmail } from '../../shared/hash-email.js';
+import { resolveDeclaredId } from '../../shared/frontmatter-id.js';
+import { isSafeSkillName, parseSkillFrontmatter } from './skills.service.js';
+const SKILL_DOC = 'SKILL.md';
+/**
+ * Skills that exist only on an open change request — proposed, not released.
+ *
+ * The catalog (`SkillService`) is pinned to the default branch, which is the
+ * right answer for everything that LOADS a skill and the wrong one for the
+ * person who just proposed it: a change request that ADDS a skill folder has
+ * nothing on the default branch to hang itself off, so until it merged the
+ * proposal was invisible to its author and to the people who had to approve it.
+ * This service is that missing half, and it is deliberately a separate surface
+ * rather than a widening of the catalog — an unapproved skill must never become
+ * loadable just because it became visible.
+ *
+ * WHO MAY SEE ONE is narrower than who may see the catalog: the author, and
+ * whoever could approve it. "Could approve it" is not re-stated here as a
+ * group-admin check — it is `canWrite` on the SKILL.md the request would
+ * create. The new folder carries no `access.md` of its own, so that verdict
+ * inherits from the group folder, which IS the group's admin; asking the access
+ * tree keeps this surface and the merge gate answering with one voice, and it
+ * keeps working for skills nested in a category subfolder that carries rules of
+ * its own.
+ *
+ * Everything degrades to "nothing pending" rather than throwing: this hangs off
+ * the library's list load, and a review surface that cannot answer must not
+ * take the shelf down with it.
+ */
+export class PendingSkillsService {
+    workspaceService;
+    accessControl;
+    skillService;
+    workflow;
+    constructor(workspaceService, accessControl, skillService, workflow) {
+        this.workspaceService = workspaceService;
+        this.accessControl = accessControl;
+        this.skillService = skillService;
+        this.workflow = workflow;
+    }
+    async listPendingSkills(userEmail) {
+        const email = userEmail.trim().toLowerCase();
+        if (!email)
+            return [];
+        let crs;
+        try {
+            crs = (await this.workflow.listChangeRequests()).filter((c) => c.state === 'open');
+        }
+        catch {
+            return [];
+        }
+        if (crs.length === 0)
+            return [];
+        // The released set, UNFILTERED by the caller's read access. A skill someone
+        // else can read and this caller cannot is still released — counting it as
+        // pending would invent a review that is not happening, and would leak the
+        // fact that the folder exists.
+        let released;
+        try {
+            released = new Set((await this.skillService.listSkills()).map((s) => s.path));
+        }
+        catch {
+            return [];
+        }
+        const candidates = crs.flatMap((cr) => cr.touchedNodePaths
+            .filter((p) => isSkillDoc(p) && !released.has(folderOf(p)))
+            .map((p) => ({ cr, docPath: p, folder: folderOf(p) })));
+        if (candidates.length === 0)
+            return [];
+        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        const authorHash = hashEmail(email);
+        // One access load for every candidate. Resolved on the DEFAULT branch —
+        // the tree as it stands is what says who owns the group the skill is
+        // arriving into; the branch's own copy is written by the proposer and must
+        // not get a say in who reviews them.
+        const writable = await this.accessControl
+            .canWriteBatch(wsId, email, candidates.map((c) => c.docPath))
+            .catch(() => new Map());
+        // The branch copies are read through the default branch's clone at
+        // `origin/<branch>`, so a proposal never needs a clone of its own. Refresh
+        // first, best-effort: a request pushed seconds ago is worth one fetch, and
+        // a failed fetch should degrade to "read what we have".
+        await this.workspaceService.ensureRemotesFetched(wsId).catch(() => undefined);
+        const out = [];
+        for (const { cr, docPath, folder } of candidates) {
+            const isAuthor = !!cr.authorId && cr.authorId === authorHash;
+            // Fail closed, matching the catalog: only an explicit `true` admits a
+            // reviewer. A missing entry (the batch skipped the path, the tree could
+            // not be read) means denied, never shown.
+            if (!isAuthor && writable.get(docPath) !== true)
+                continue;
+            const raw = await this.readAt(wsId, cr.branch, docPath);
+            // Nothing to describe: the request touched the path but the file is gone
+            // at its head (proposed then withdrawn within the branch), or unreadable.
+            if (raw === null)
+                continue;
+            const fm = parseSkillFrontmatter(raw);
+            const folderName = folder.split('/').pop() ?? folder;
+            const declared = resolveDeclaredId(fm.frontmatter, folderName);
+            out.push({
+                name: isSafeSkillName(declared) ? declared : folderName,
+                description: fm.description,
+                version: fm.version,
+                path: folder,
+                changeRequestNumber: cr.number,
+                branch: cr.branch,
+                authorName: cr.appAuthor?.name ?? cr.author.name ?? 'Someone',
+                createdAt: cr.createdAt,
+                isAuthor,
+            });
+        }
+        // Oldest first — the one that has been waiting longest is the one that
+        // needs answering, and a list that reorders as requests arrive moves under
+        // the pointer.
+        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    /** The file at a branch, or null when it is absent/unreadable there. */
+    async readAt(wsId, branch, repoRelPath) {
+        try {
+            return await this.workspaceService.readFileAtRef(wsId, `origin/${branch}`, repoRelPath);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Is this touched path a skill's own SKILL.md?
+ *
+ * `Groups/<group>/<skill>/SKILL.md` is the shallowest shape, hence four
+ * segments; deeper ones are skills nested in a category subfolder, which the
+ * catalog already supports. `Groups/<group>/SKILL.md` is NOT a skill — a group
+ * folder is not itself one.
+ */
+function isSkillDoc(repoRelPath) {
+    const segments = repoRelPath.split('/');
+    return (segments.length >= 4 &&
+        segments[0] === GROUPS_DIR &&
+        segments[segments.length - 1] === SKILL_DOC);
+}
+/** The skill folder holding a SKILL.md. */
+function folderOf(skillDocPath) {
+    return skillDocPath.slice(0, -(SKILL_DOC.length + 1));
+}
+//# sourceMappingURL=pending-skills.service.js.map

package/dist/modules/skills/pending-skills.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-skills.service.js","sourceRoot":"","sources":["../../../src/modules/skills/pending-skills.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/skills/skills.contract.d.ts

@@ -1,5 +1,5 @@
 /**
- * Skills are reusable specialist instructions living under `Skills/<name>/SKILL.md`
+ * Skills are reusable specialist instructions living under `Groups/<group>/<name>/SKILL.md`
  * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
  * is a single global, released set (a skill on a draft isn't discoverable until
  * merged). Progressive disclosure: `listSkills` = name + description (level 1),
@@ -11,7 +11,7 @@ export interface SkillSummary {
     name: string;
     description: string;
     version?: string;
-    /** Repo-root-relative skill folder, e.g. `Skills/rfi`. */
+    /** Repo-root-relative skill folder, e.g. `Groups/Everyone/rfi`. */
     path: string;
 }
 export interface Skill extends SkillSummary {
@@ -19,7 +19,7 @@ export interface Skill extends SkillSummary {
     body: string;
     /** Pre-approved tools from the `allowed-tools` frontmatter, if declared. */
     allowedTools?: string[];
-    /** Repo-root-relative bundled file paths, e.g. `Skills/rfi/scripts/build_xlsx.py`. */
+    /** Repo-root-relative bundled file paths, e.g. `Groups/Everyone/rfi/scripts/build_xlsx.py`. */
     files: string[];
 }
 export interface SkillFileContent {
@@ -43,6 +43,35 @@ export type GetSkillResult = {
     ok: false;
     error: 'not_found' | 'forbidden' | 'invalid_file';
 };
+/**
+ * A skill that exists ONLY on an open change request's branch — proposed, not
+ * released. It is deliberately NOT a `SkillSummary` the catalog returns: the
+ * catalog is what agents load, and a skill nobody has approved must not be
+ * loadable. This is a review surface only.
+ *
+ * Who may see one is narrower than who may see the catalog: its author, and
+ * whoever could approve it. See `PendingSkillsService` for why that predicate
+ * is the access tree's answer rather than a group-admin check spelled out
+ * again here.
+ */
+export interface PendingSkill extends SkillSummary {
+    /** The open change request that would release it. */
+    changeRequestNumber: number;
+    branch: string;
+    /** Display name of whoever opened the request (person or agent). */
+    authorName: string;
+    createdAt: string;
+    /** True when the caller opened the request themselves. */
+    isAuthor: boolean;
+}
+export interface IPendingSkillService {
+    /**
+     * Skills awaiting approval that `userEmail` is entitled to see — the ones
+     * they proposed, and the ones they could approve. Never throws: a review
+     * surface failing must not take the library down with it.
+     */
+    listPendingSkills(userEmail: string): Promise<PendingSkill[]>;
+}
 export interface ISkillService {
     /**
      * The default-branch skill catalog. When `userEmail` is given, filtered to