@bevel-software/platform-core-backend 0.25.2 → 0.26.0

package/dist/modules/workspace/startup/steps/template-files.step.d.ts

@@ -1,7 +1,9 @@
 import { type KbLayout } from '@bevel-software/platform-shared';
 import { type IFsProbe } from '../../../../shared/fs.contract.js';
 import type { KbContext } from '../../../../shared/kb-context.js';
+import { isManagedGuide } from '../../../agent-guide/agent-guide.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+export { isManagedGuide };
 /**
  * The **required scaffolding** — the minimum an operational KB needs. Any of
  * these missing from a protected branch are added at the startup phase; the
@@ -17,11 +19,11 @@ import type { OnServerStart, ServerStartContext, StepResult } from '../on-server
  *
  * `roles.yaml` is in neither, and is not part of the template at all: it is
  * generated from `ADMIN_EMAIL` (see roles-yaml.step.ts), so a repo can't be
- * seeded with a stale hard-coded Admin list.
+ * seeded with a stale hard-coded Admin list. The agent guide is in neither
+ * either, any more: it is served from code (see modules/agent-guide), and the
+ * copies earlier releases wrote are REMOVED here, not refreshed.
  */
-export declare function requiredFiles(layout: Required<KbLayout>): readonly string[];
-/** Whether `text` is a copy of the platform's managed guide, of any vintage. */
-export declare function isManagedGuide(text: string): boolean;
+export declare function requiredFiles(_layout: Required<KbLayout>): readonly string[];
 /**
  * Repo-root files the startup phase GENERATES rather than copies — today just
  * `roles.yaml`, rendered from `ADMIN_EMAIL` (see roles-yaml.step.ts and
@@ -42,13 +44,16 @@ export declare const GENERATED_FILES: readonly string[];
 export declare function reservedRootDirs(extraRootDirs: readonly string[], layout: Required<KbLayout>): readonly string[];
 /**
  * The template top-up as an {@link OnServerStart} step: add any missing base
- * scaffolding to every PROTECTED branch, and keep the managed agent guide
- * current — under whatever this deployment calls it, and taking its own
- * stale `AGENTS.md` with it when that name was handed back to the customer. Drafts are deliberately out of scope — whatever the protected
- * branches gain, drafts fork from; a scaffolding addition on a draft would
- * surface as noise in its change request's diff. (Unlike the Groups→Plugins
- * rename, a missing file diffs as one file, not the whole tree — so the
- * uniform-application argument does not bite here.)
+ * scaffolding to every PROTECTED branch, and take the agent guide copies
+ * earlier releases wrote OUT of them — the guide is served from code now, and
+ * a copy left on disk would be read as the organisation's own conventions
+ * file, stale and under a header that says the platform owns it. Drafts are
+ * deliberately out of scope — whatever the protected branches gain, drafts
+ * fork from; a scaffolding addition on a draft would surface as noise in its
+ * change request's diff. (Unlike the Groups→Plugins rename, a missing file
+ * diffs as one file, not the whole tree — so the uniform-application argument
+ * does not bite here. A stale guide copy on a draft is recognised by its
+ * header and never served, see `modules/agent-guide`.)
  *
  * Everything is DECLARED on the branch handle; reads go against the pre-step
  * tree via `repoDir()`. Fail-open behavior from the lazy top-up (best-effort,
@@ -65,7 +70,6 @@ export declare class TemplateFilesStep implements OnServerStart {
      */
     private readonly kb;
     private readonly extraRootDirs;
-    private readonly agentsFileLink;
     readonly name = "template-files";
     /**
      * @param extraRootDirs Additional root folders this distribution reserves,
@@ -74,45 +78,39 @@ export declare class TemplateFilesStep implements OnServerStart {
      *                      claim a root without also shipping a template entry
      *                      for it.
      */
-    /**
-     * @param agentsFileLink Whether to keep the platform's pointer sentence in a
-     *                       customer-owned root `AGENTS.md` — a GETTER, because
-     *                       the setting behind it may be saved by the very
-     *                       first-run save that then runs this phase.
-     */
     constructor(disk: IFsProbe, 
     /**
      * Read per run, never captured: the save that completes first-run setup
      * applies the admin's names after this step was built. A snapshot taken
      * here scaffolded `Skills/` beside the `skills/` they had just chosen.
      */
-    kb: Pick<KbContext, 'layout'>, extraRootDirs?: readonly string[], agentsFileLink?: () => boolean);
+    kb: Pick<KbContext, 'layout'>, extraRootDirs?: readonly string[]);
     run(ctx: ServerStartContext): Promise<StepResult>;
     private topUp;
     /**
-     * The root `AGENTS.md` on a deployment whose guide is called something else:
-     * removed when the platform can PROVE it wrote it, otherwise left alone —
-     * and, while the admin keeps the link setting on, given the one sentence
-     * that points at the guide beside it.
-     *
-     * Removal is gated on the managed header and nothing else. An admin who
-     * renames the guide on a knowledge base the platform seeded would otherwise
-     * be left with stale platform content sitting under the very name they
-     * wanted for their own file; an admin who renames it on a repository whose
-     * `AGENTS.md` is their own must find that file byte-for-byte untouched. The
-     * header is the one fact that tells the two apart, so it is the one thing
-     * asked.
+     * The copies of the guide the platform wrote to the repository root while
+     * the guide was a file — under `AGENTS.md`, under `CLAUDE.md` from before
+     * the rename, and under every name a deployment ever gave the guide —
+     * removed when the platform can PROVE it wrote them, and otherwise left
+     * exactly alone.
      *
-     * The pointer is bounded by three conditions, all of them the customer's to
-     * control: the admin keeps the setting on, the file exists (one is NEVER
-     * created for this), and the guide's name appears nowhere in the text. That
-     * last one is a plain content search on purpose — a mention in the
-     * customer's own words, a link, a heading, all count, and the platform stays
-     * out of a file it does not own.
+     * Found by SCANNING the root's markdown files rather than by the names the
+     * deployment knows today: a deployment that renamed the guide more than
+     * once left a copy under each earlier name, and the current setting
+     * remembers only the last. The header is what makes a scan safe, and the
+     * one fact that tells a copy of ours from a file of theirs: the
+     * organisation's own `AGENTS.md`, a `CLAUDE.md` its people edited, a note
+     * of theirs that happens to sit at the root, must all be found byte for
+     * byte untouched. A SYMLINK or a directory is left as it is: reading a link
+     * follows it, so a link pointing at a copy of the guide — or at any other
+     * file carrying the header — would read as ours and the removal would take
+     * the organisation's entry. Links are never followed anywhere else in the
+     * platform, and they are not followed here.
      *
-     * Returns the paths changed, for the note.
+     * Returns the names removed, in name order, for the note and for the
+     * ignore rules that hid them.
      */
-    private reconcileLegacyGuide;
+    private retireGuideCopies;
     /**
      * Which reserved roots are absent — and which are SQUATTED. `lstat`, not
      * `exists`: `fs.access` answers "is there something here?", which is true of
@@ -167,23 +165,31 @@ export declare class TemplateFilesStep implements OnServerStart {
  * branches this step never visits (drafts).
  */
 export declare function withoutIgnoreLine(text: string, pattern: string): string;
+/**
+ * `text` without the rules THE PLATFORM WROTE to hide the guide while it was a
+ * file. Under WHATEVER name: every rule sitting directly under one of the two
+ * comments the platform wrote above the guide's rule
+ * ({@link withoutPlatformConventionsRules}) — the name a deployment saved for
+ * the guide is not read any more, so the rule for it is known by its comment
+ * and by nothing else. Then the two names the template itself shipped a rule
+ * for, under each of `names`: the `AGENTS.md` line in the slot at the end of
+ * the template's own repo-hygiene block
+ * ({@link TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE}) and the `CLAUDE.md` line
+ * under the two-line comment the template carried it with. Each goes with
+ * its comment.
+ *
+ * The guide is not on disk any more, which is what makes every one of these
+ * lines wrong: it hides a file the platform never writes, which is therefore
+ * the organisation's own. A `!AGENTS.md` negation is not the rule and stays,
+ * as everywhere else here, and so does a bare rule an operator wrote by hand.
+ */
+export declare function withoutPlatformGuideRules(text: string, names: readonly string[]): string;
 /**
  * `text` without the `AGENTS.md` line THE PLATFORM WROTE — under its own
  * comment (either spelling), or in the slot at the end of the template's own
  * repo-hygiene block ({@link TEMPLATE_HYGIENE_BLOCK_ABOVE_AGENTS_RULE}) — and
- * without that comment.
- *
- * Called only when the guide has been renamed, which is what makes the line
- * wrong: it hides a file the platform no longer owns. A `!AGENTS.md` negation
- * is not the rule and stays, as everywhere else here.
+ * without that comment. A `!AGENTS.md` negation is not the rule and stays, as
+ * everywhere else here.
  */
 export declare function withoutPlatformAgentsRule(text: string): string;
-/**
- * `text` with the platform's pointer sentence appended as its own paragraph.
- *
- * One blank line between the customer's last line and ours, whether or not
- * their file ended in a newline: a sentence glued onto the end of their last
- * paragraph would read as a continuation of something they wrote.
- */
-export declare function withPointerSentence(text: string, agentsFile: string): string;
 //# sourceMappingURL=template-files.step.d.ts.map

package/dist/modules/workspace/startup/steps/template-files.step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-files.step.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/template-files.step.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAGlE,OAAO,KAAK,EAAY,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMrG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,MAAM,EAAE,CAgB3E;AAwBD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAmB,CAAC;AA8CjE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,MAAM,EAAE,CAchH;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAiBnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAxBjC,QAAQ,CAAC,IAAI,oBAAoB;IAEjC;;;;;;OAMG;IACH;;;;;OAKG;gBAEgB,IAAI,EAAE,QAAQ;IAC/B;;;;OAIG;IACc,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAC7B,aAAa,GAAE,SAAS,MAAM,EAAO,EACrC,cAAc,GAAE,MAAM,OAAoB;IAOvD,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;YAOzC,KAAK;IAgKnB;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,oBAAoB;IAoElC;;;;;;;;;;OAUG;YACW,WAAW;IAiBzB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;OAeG;YACW,oBAAoB;CA0CnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcvE;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwB9D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG5E"}
+{"version":3,"file":"template-files.step.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/template-files.step.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAErE,OAAO,KAAK,EAAY,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGrG,OAAO,EAAE,cAAc,EAAE,CAAC;AAY1B;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,MAAM,EAAE,CAW5E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAmB,CAAC;AA8CjE;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,MAAM,EAAE,CAchH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAWnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAjBhC,QAAQ,CAAC,IAAI,oBAAoB;IAEjC;;;;;;OAMG;gBAEgB,IAAI,EAAE,QAAQ;IAC/B;;;;OAIG;IACc,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAC7B,aAAa,GAAE,SAAS,MAAM,EAAO;IAOlD,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;YAOzC,KAAK;IAqInB;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,iBAAiB;IAyB/B;;;;;;;;;;OAUG;YACW,WAAW;IAiBzB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;OAeG;YACW,oBAAoB;CAuCnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcvE;AAwCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAOxF;AAiED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwB9D"}