@jskit-ai/agent-docs 0.1.24 → 0.1.26

package/guide/agent/generators/advanced-cruds.md

@@ -109,6 +109,35 @@ So if the CRUD resolves to:
 
 This is why ownership is such a foundational choice. It becomes part of the generated server contract, not just the database shape.
 
+### `--internal` changes HTTP exposure, not CRUD ownership
+
+`crud-server-generator scaffold` also supports:
+
+```bash
+--internal
+```
+
+That flag does **not** change:
+
+- the generated repository
+- the generated service
+- the shared resource contract
+- the ownership filter
+- the generated actions
+
+It changes only one thing:
+
+- the generated CRUD HTTP routes are marked internal, so the public HTTP runtime does not register them
+
+This is useful when the entity should already be CRUD-owned but should not have public CRUD URLs yet.
+
+So the distinction is:
+
+- ownership answers "who owns and can see the rows?"
+- `--internal` answers "do the public HTTP CRUD routes exist right now?"
+
+That is why `--internal` is not a permissions shortcut and not a UI setting. It is a server-route exposure choice on top of the same CRUD ownership model.
+
 ### Ownership controls which owner columns are expected
 
 The repository layer ultimately applies visibility through the standard owner columns:

package/guide/agent/generators/crud-generators.md

@@ -262,6 +262,22 @@ npx jskit generate crud-server-generator scaffold \
 
 This creates an app-local package under `packages/contacts/`.
 
+If the table should be CRUD-owned now but should **not** expose public HTTP CRUD routes yet, add:
+
+```bash
+--internal
+```
+
+That keeps the generated repository, service, actions, provider, shared resource, and CRUD migration ownership chain exactly the same. The only difference is that the generated HTTP CRUD routes are marked internal, so the public HTTP runtime does not register them.
+
+Use that when:
+
+- other server modules need a proper CRUD-backed table and shared resource contract
+- you want to avoid direct knex
+- you are not ready to expose list/view/create/update/delete URLs yet
+
+Do **not** use `--internal` as a substitute for ownership or permissions design. It is only about whether the public HTTP CRUD routes exist.
+
 Before generating anything, decide these with the developer:
 
 - which operations are allowed for this CRUD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Distributed JSKIT agent workflows, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/crud-scaffolding.md

@@ -19,12 +19,19 @@ Rules:
 - For a CRUD-backed entity, start with `jskit generate crud-server-generator scaffold ...`.
 - Unless the table is already owned by a JSKIT baseline package or is an explicit narrow exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must go through that server CRUD step first.
 - That server scaffold is the crucial first step even if no CRUD UI will be created yet.
+- If the table should be CRUD-owned now but should not expose public CRUD HTTP routes yet, scaffold it with `jskit generate crud-server-generator scaffold ... --internal` instead of dropping to direct knex or a hand-built pseudo-repository.
 - Create the real table directly in the database before scaffolding. `crud-server-generator` reads the live table shape.
 - If `crud-server-generator` is going to own the CRUD, do not hand-write a separate CRUD migration for that table. The generator installs and manages the CRUD migration scaffold itself.
 - Do not scaffold CRUD UI, hand-build CRUD routes, or hand-build CRUD endpoints before the server CRUD package and shared resource file exist.
 - Treat the generated shared resource file as the canonical CRUD contract for later UI scaffolding and CRUD behavior changes.
 - `feature-server-generator` is not the default lane for ordinary persisted entities. Use it for workflows or orchestration that sit on top of CRUD-owned tables, or for rare explicit non-CRUD exceptions.
 
+Meaning of `--internal`:
+
+- it keeps the generated repository, service, actions, provider, resource, and CRUD migration ownership chain
+- it only suppresses public HTTP CRUD route registration
+- it is not a substitute for ownership columns or action/route permissions
+
 Avoid:
 
 - writing a hand migration for a CRUD table that JSKIT CRUD scaffolding is supposed to own

package/reference/autogen/packages/crud-server-generator.md

@@ -27,6 +27,7 @@ Local functions
 - `resolveAllowedValues(schema = {}, fallbackValues = [])`
 - `resolveGlobalScaffoldCache()`
 - `asRecord(value)`
+- `resolveInternalRouteOption(options = {})`
 - `normalizeRequestedOwnershipFilter(value, { strict = false } = {})`
 - `inferOwnershipFilterFromSnapshot(snapshot)`
 - `assertOwnershipColumnsForFilter(snapshot, filter)`
@@ -94,7 +95,7 @@ Local functions
 - `renderObjectSchemaDefinition(lines = [], { mode = "patch" } = {})`
 - `renderActionInputExpressions({ surfaceRequiresWorkspace = true } = {})`
 - `renderRouteValidatorConstants({ surfaceRequiresWorkspace = true } = {})`
-- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "" })`
+- `buildReplacementsFromSnapshot({ namespace = "", snapshot, resolvedOwnershipFilter, surfaceRequiresWorkspace = true, surfaceId = "", routeInternal = false })`
 - `resolveCrudGenerationTableName(options = {})`
 - `createCacheKey({ appRoot, options })`
 - `buildCrudTemplateContext(input = {})`
@@ -201,7 +202,7 @@ Exports
 - `resource`
 - `createTemplateServerFixture(options = {})`
 Local functions
-- `buildTemplateReplacements({ surfaceRequiresWorkspace = true, requiresNamedPermissions = surfaceRequiresWorkspace === true, surfaceId = surfaceRequiresWorkspace ? "admin" : "home" } = {})`
+- `buildTemplateReplacements({ surfaceRequiresWorkspace = true, requiresNamedPermissions = surfaceRequiresWorkspace === true, surfaceId = surfaceRequiresWorkspace ? "admin" : "home", routeInternal = false } = {})`
 - `applyTemplateReplacements(sourceText = "", options = {})`
 - `buildResourceStubSource()`
 - `renderServerTemplateFile(targetServerDirectory, fileName, options)`

package/reference/autogen/packages/kernel.md

@@ -870,6 +870,7 @@ Local functions
 - `normalizeMethod(method)`
 - `normalizePath(pathname)`
 - `normalizeRouterMiddlewareStack(value, { context = "middleware" } = {})`
+- `normalizeRouteInternal(value, { method = "", path = "" } = {})`
 - `normalizeRouteInput(method, path, optionsOrHandler, maybeHandler)`
 
 ### `server/http/lib/routeRegistration.js`

package/templates/app/AGENTS.md

@@ -73,6 +73,7 @@ Core rules:
 - For CRUD chunks, creating the server CRUD with `jskit generate crud-server-generator scaffold ...` is the crucial first step even if no CRUD UI will be created yet.
 - Unless a table is already owned by a JSKIT baseline package or is an explicit narrow exception recorded in `.jskit/table-ownership.json`, every persisted app-owned table must have its own server CRUD package created first with `jskit generate crud-server-generator scaffold ...`, even if no CRUD UI will ever exist.
 - Treat that as a hard invariant, not a style preference. If a persisted app-owned table does not have generated CRUD ownership, `jskit doctor` is expected to fail.
+- If the table should be CRUD-owned but should not expose public CRUD HTTP routes yet, use `jskit generate crud-server-generator scaffold ... --internal` rather than dropping to direct knex or a hand-built pseudo-repository.
 - For a CRUD table that `crud-server-generator` will own, do not hand-write a separate migration. Create the real table directly in the database first, then scaffold the server CRUD so JSKIT can install and manage the CRUD migration scaffold itself.
 - Do not generate CRUD UI or hand-build CRUD routes before the server CRUD package and shared resource file exist.
 - `feature-server-generator` is for workflows, orchestration, and other non-CRUD server features. Do not use it as the starting point for ordinary persisted entity tables.