@antasphere/chassis-contract 1.6.0 → 1.8.0

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './schemas/webhooks.js';
 export * from './schemas/connections.js';
 export * from './schemas/demo-passes.js';
 export * from './schemas/apps.js';
+export * from './schemas/docs-source.js';
 export * from './fleet.js';
 export * from './tools.js';
 export * from './seams.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -26,6 +26,7 @@ export * from './schemas/webhooks.js';
 export * from './schemas/connections.js';
 export * from './schemas/demo-passes.js';
 export * from './schemas/apps.js';
+export * from './schemas/docs-source.js';
 export * from './fleet.js';
 export * from './tools.js';
 export * from './seams.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,2EAA2E;AAC3E,qEAAqE;AACrE,8EAA8E;AAC9E,oFAAoF;AACpF,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAA4B,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EAKrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,2EAA2E;AAC3E,qEAAqE;AACrE,8EAA8E;AAC9E,oFAAoF;AACpF,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAA4B,MAAM,iBAAiB,CAAC;AACtF,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EAKrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}

package/dist/schemas/docs-source.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+/**
+ * The docs source (PRDCT-4098): what a tool answers on `GET /docs-source`,
+ * read from the `docs/` folder its image carries, to a direct network peer
+ * presenting `Authorization: Bearer <DOCS_SOURCE_TOKEN>` (off when the tool
+ * has no token; a request through a proxy answers 404). A
+ * reader (the Handbook) validates the answer with this schema, the way
+ * `toolOriginsSchema` guards the fleet read.
+ *
+ * - `product`, `description`: `docs/nav.yml`'s own keys.
+ * - `version`: the instance's reported version (`APP_VERSION`); `slug`: the
+ *   tool identity's slug. Together they say what was read.
+ * - `groups`: `nav.yml`'s groups in order, each page with its `path` (as
+ *   `nav.yml` lists it, no `.md`), its `title` (the page's leading H1) and its
+ *   `description` (the intro paragraph under the H1, inline markdown
+ *   flattened to text: the public docs site's page contract; empty when the
+ *   page has none). A page `nav.yml` lists but the folder lacks is left out.
+ *
+ * A page's markdown is `GET /docs-source/pages/<path>` for a `path` listed
+ * here, `text/markdown; charset=utf-8`; every other path answers 404.
+ */
+export declare const docsSourcePageSchema: z.ZodObject<{
+    path: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+export type DocsSourcePage = z.infer<typeof docsSourcePageSchema>;
+export declare const docsSourceGroupSchema: z.ZodObject<{
+    title: z.ZodString;
+    pages: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DocsSourceGroup = z.infer<typeof docsSourceGroupSchema>;
+export declare const docsSourceManifestSchema: z.ZodObject<{
+    product: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    slug: z.ZodString;
+    groups: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        pages: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DocsSourceManifest = z.infer<typeof docsSourceManifestSchema>;
+/** The route's paths, for a reader that builds the URLs. */
+export declare const DOCS_SOURCE_PATH = "/docs-source";
+export declare const DOCS_SOURCE_PAGES_PATH = "/docs-source/pages";
+//# sourceMappingURL=docs-source.d.ts.map

package/dist/schemas/docs-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-source.d.ts","sourceRoot":"","sources":["../../src/schemas/docs-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB;;;;iBAI/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;iBAGhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;iBAMnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAC/C,eAAO,MAAM,sBAAsB,uBAAuB,CAAC"}

package/dist/schemas/docs-source.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/**
+ * The docs source (PRDCT-4098): what a tool answers on `GET /docs-source`,
+ * read from the `docs/` folder its image carries, to a direct network peer
+ * presenting `Authorization: Bearer <DOCS_SOURCE_TOKEN>` (off when the tool
+ * has no token; a request through a proxy answers 404). A
+ * reader (the Handbook) validates the answer with this schema, the way
+ * `toolOriginsSchema` guards the fleet read.
+ *
+ * - `product`, `description`: `docs/nav.yml`'s own keys.
+ * - `version`: the instance's reported version (`APP_VERSION`); `slug`: the
+ *   tool identity's slug. Together they say what was read.
+ * - `groups`: `nav.yml`'s groups in order, each page with its `path` (as
+ *   `nav.yml` lists it, no `.md`), its `title` (the page's leading H1) and its
+ *   `description` (the intro paragraph under the H1, inline markdown
+ *   flattened to text: the public docs site's page contract; empty when the
+ *   page has none). A page `nav.yml` lists but the folder lacks is left out.
+ *
+ * A page's markdown is `GET /docs-source/pages/<path>` for a `path` listed
+ * here, `text/markdown; charset=utf-8`; every other path answers 404.
+ */
+export const docsSourcePageSchema = z.object({
+    path: z.string().min(1),
+    title: z.string(),
+    description: z.string()
+});
+export const docsSourceGroupSchema = z.object({
+    title: z.string(),
+    pages: z.array(docsSourcePageSchema)
+});
+export const docsSourceManifestSchema = z.object({
+    product: z.string(),
+    description: z.string(),
+    version: z.string(),
+    slug: z.string(),
+    groups: z.array(docsSourceGroupSchema)
+});
+/** The route's paths, for a reader that builds the URLs. */
+export const DOCS_SOURCE_PATH = '/docs-source';
+export const DOCS_SOURCE_PAGES_PATH = '/docs-source/pages';
+//# sourceMappingURL=docs-source.js.map

package/dist/schemas/docs-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-source.js","sourceRoot":"","sources":["../../src/schemas/docs-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;CACvC,CAAC,CAAC;AAGH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antasphere/chassis-contract",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -35,6 +35,7 @@ export * from './schemas/webhooks.js';
 export * from './schemas/connections.js';
 export * from './schemas/demo-passes.js';
 export * from './schemas/apps.js';
+export * from './schemas/docs-source.js';
 export * from './fleet.js';
 export * from './tools.js';
 export * from './seams.js';

package/src/schemas/docs-source.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+/**
+ * The docs source (PRDCT-4098): what a tool answers on `GET /docs-source`,
+ * read from the `docs/` folder its image carries, to a direct network peer
+ * presenting `Authorization: Bearer <DOCS_SOURCE_TOKEN>` (off when the tool
+ * has no token; a request through a proxy answers 404). A
+ * reader (the Handbook) validates the answer with this schema, the way
+ * `toolOriginsSchema` guards the fleet read.
+ *
+ * - `product`, `description`: `docs/nav.yml`'s own keys.
+ * - `version`: the instance's reported version (`APP_VERSION`); `slug`: the
+ *   tool identity's slug. Together they say what was read.
+ * - `groups`: `nav.yml`'s groups in order, each page with its `path` (as
+ *   `nav.yml` lists it, no `.md`), its `title` (the page's leading H1) and its
+ *   `description` (the intro paragraph under the H1, inline markdown
+ *   flattened to text: the public docs site's page contract; empty when the
+ *   page has none). A page `nav.yml` lists but the folder lacks is left out.
+ *
+ * A page's markdown is `GET /docs-source/pages/<path>` for a `path` listed
+ * here, `text/markdown; charset=utf-8`; every other path answers 404.
+ */
+export const docsSourcePageSchema = z.object({
+  path: z.string().min(1),
+  title: z.string(),
+  description: z.string()
+});
+export type DocsSourcePage = z.infer<typeof docsSourcePageSchema>;
+
+export const docsSourceGroupSchema = z.object({
+  title: z.string(),
+  pages: z.array(docsSourcePageSchema)
+});
+export type DocsSourceGroup = z.infer<typeof docsSourceGroupSchema>;
+
+export const docsSourceManifestSchema = z.object({
+  product: z.string(),
+  description: z.string(),
+  version: z.string(),
+  slug: z.string(),
+  groups: z.array(docsSourceGroupSchema)
+});
+export type DocsSourceManifest = z.infer<typeof docsSourceManifestSchema>;
+
+/** The route's paths, for a reader that builds the URLs. */
+export const DOCS_SOURCE_PATH = '/docs-source';
+export const DOCS_SOURCE_PAGES_PATH = '/docs-source/pages';

package/test/docs-source.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { DOCS_SOURCE_PAGES_PATH, DOCS_SOURCE_PATH, docsSourceManifestSchema } from '../src/index.js';
+
+/** The docs source manifest (PRDCT-4098): the shape a reader (the Handbook) validates. */
+describe('docsSourceManifestSchema', () => {
+  const manifest = {
+    product: 'Your Tool',
+    description: 'A tool.',
+    version: '1.8.0',
+    slug: 'yourtool',
+    groups: [
+      { title: 'Getting started', pages: [{ path: 'index', title: 'Your Tool', description: 'Intro.' }] },
+      { title: 'Empty', pages: [] }
+    ]
+  };
+
+  it('accepts the route answer', () => {
+    expect(docsSourceManifestSchema.parse(manifest)).toEqual(manifest);
+  });
+
+  it('accepts an empty description and keeps an additive field out', () => {
+    const parsed = docsSourceManifestSchema.parse({ ...manifest, description: '', extra: 1 });
+    expect(parsed.description).toBe('');
+    expect('extra' in parsed).toBe(false);
+  });
+
+  it.each([
+    ['no version', { ...manifest, version: undefined }],
+    ['no slug', { ...manifest, slug: undefined }],
+    ['no groups', { ...manifest, groups: undefined }],
+    [
+      'a page without a path',
+      { ...manifest, groups: [{ title: 'G', pages: [{ title: 'T', description: '' }] }] }
+    ],
+    [
+      'an empty path',
+      { ...manifest, groups: [{ title: 'G', pages: [{ path: '', title: 'T', description: '' }] }] }
+    ],
+    ['a group without pages', { ...manifest, groups: [{ title: 'G' }] }],
+    [
+      'a page without a title',
+      { ...manifest, groups: [{ title: 'G', pages: [{ path: 'p', description: '' }] }] }
+    ]
+  ])('refuses %s', (_what, value) => {
+    expect(docsSourceManifestSchema.safeParse(value).success).toBe(false);
+  });
+
+  it('names the two paths', () => {
+    expect(DOCS_SOURCE_PATH).toBe('/docs-source');
+    expect(DOCS_SOURCE_PAGES_PATH).toBe('/docs-source/pages');
+  });
+});