@noormdev/sdk 1.0.0-alpha.36 → 1.0.0-alpha.38

package/dist/index.d.ts

@@ -70,6 +70,32 @@ export interface ConnectionResult {
  * - verbose: All events including debug
  */
 export type LogLevel = "silent" | "error" | "warn" | "info" | "verbose";
+/**
+ * Access policy data model.
+ *
+ * Roles live on the config, not the actor — the actor is a channel (who is
+ * asking), and each config declares what each channel is allowed to do.
+ */
+/**
+ * A config-scoped access level. Ordered loosest to strictest in practice:
+ * `viewer` reads only, `operator` writes and confirms destructive ops,
+ * `admin` is frictionless.
+ */
+export type Role = "viewer" | "operator" | "admin";
+/**
+ * Who is asking — CLI/TUI/SDK callers are `user`, the MCP server is `mcp`.
+ * Not an identity system; there are no user accounts.
+ */
+export type Channel = "user" | "mcp";
+/**
+ * Per-channel access for a config. `mcp: false` means the config is
+ * invisible on the MCP channel — not a role, and never consulted by
+ * `checkPolicy` (visibility is enforced upstream of policy).
+ */
+export interface ConfigAccess {
+	user: Role;
+	mcp: Role | false;
+}
 /**
  * Full configuration object.
  *
@@ -79,7 +105,7 @@ export type LogLevel = "silent" | "error" | "warn" | "info" | "verbose";
  *     name: 'dev',
  *     type: 'local',
  *     isTest: false,
- *     protected: false,
+ *     access: { user: 'admin', mcp: 'admin' },
  *     connection: {
  *         dialect: 'postgres',
  *         host: 'localhost',
@@ -95,7 +121,12 @@ export interface Config {
 	name: string;
 	type: "local" | "remote";
 	isTest: boolean;
-	protected: boolean;
+	/**
+	 * Per-channel access roles — the source of truth for policy checks
+	 * (`checkPolicy`/`guarded` from `core/policy`). Every config materialized
+	 * through `parseConfig`/state load has it populated.
+	 */
+	access: ConfigAccess;
 	connection: ConnectionConfig;
 	identity?: string;
 }
@@ -780,13 +811,6 @@ export interface SchemaValidationResult {
 	/** Non-blocking warnings about potential issues. */
 	warnings: string[];
 }
-/**
- * Settings Types
- *
- * Settings define project-wide build behavior and stage configuration.
- * Unlike encrypted configs (credentials), settings are version controlled
- * and shared across the team via .noorm/settings.yml
- */
 /**
  * Secret type hints for CLI input handling.
  *
@@ -822,7 +846,7 @@ export interface StageSecret {
  * Stage defaults that can be overridden when creating a config.
  *
  * These provide initial values. Some are enforceable constraints:
- * - protected: true - Cannot be overridden to false
+ * - protected: true - Clamped as an access ceiling at resolution, not an override-block (`resolver.ts`)
  * - isTest: true - Cannot be overridden to false
  * - dialect - Cannot be changed after creation
  */
@@ -835,6 +859,7 @@ export interface StageDefaults {
 	password?: string;
 	ssl?: boolean;
 	isTest?: boolean;
+	/** Settings-stage vocabulary — distinct from the removed `Config.protected`; see docs/spec/config-access-roles.md. */
 	protected?: boolean;
 }
 /**
@@ -876,7 +901,7 @@ export interface Stage {
 export interface RuleMatch {
 	/** Config name (exact match) */
 	name?: string;
-	/** Protected config flag */
+	/** Settings-stage vocabulary — distinct from the removed `Config.protected`; matched against `guarded(config)`. */
 	protected?: boolean;
 	/** Test database flag */
 	isTest?: boolean;
@@ -1493,6 +1518,8 @@ export interface BatchChangeOptions extends ChangeOptions {
  *     projectRoot: '/project',
  *     changesDir: '/project/changes',
  *     sqlDir: '/project/sql',
+ *     access: { user: 'admin', mcp: 'admin' },
+ *     channel: 'user',
  * }
  * ```
  */
@@ -1509,6 +1536,14 @@ export interface ChangeContext {
 	changesDir: string;
 	/** Schema directory for resolving .txt references */
 	sqlDir: string;
+	/**
+	 * Config's per-channel access roles. `executeChange`/`revertChange`
+	 * gate on this once, at the core seam, so SDK/TUI/CLI callers inherit
+	 * one enforcement path instead of re-implementing the check per caller.
+	 */
+	access: ConfigAccess;
+	/** Caller channel for the policy gate — `user` for CLI/TUI/SDK, `mcp` for MCP. */
+	channel: Channel;
 	/** Config object for template context */
 	config?: Record<string, unknown>;
 	/** Secrets for template context */
@@ -1888,11 +1923,6 @@ declare class ChangeManager {
 	 */
 	load(name: string): Promise<Change>;
 }
-/**
- * SDK Types.
- *
- * All interfaces and types for the noorm programmatic SDK.
- */
 /**
  * Options for creating an SDK context.
  *
@@ -1932,6 +1962,12 @@ export interface CreateContextOptions {
 	requireTest?: boolean;
 	/** Stage name for stage defaults (from settings.yml) */
 	stage?: string;
+	/**
+	 * Which caller channel this context represents for access-policy checks
+	 * (`checkPolicy` in `src/sdk/guards.ts`). SDK/CLI/TUI callers are `user`;
+	 * pass `'mcp'` when the context backs an MCP session. Default: `'user'`.
+	 */
+	channel?: Channel;
 }
 /**
  * Options for build operations.
@@ -3235,6 +3271,11 @@ export interface TransferOptions {
 	exportPath?: string;
 	/** Passphrase for .dtzx export encryption. */
 	passphrase?: string;
+	/**
+	 * Caller channel for the `db:reset` policy gate against the
+	 * destination config (the write target). Default: `'user'`.
+	 */
+	channel?: Channel;
 }
 /**
  * Plan for a single table transfer.
@@ -3485,6 +3526,11 @@ export interface UpdateEvents {
 	"update:installing": {
 		version: string;
 	};
+	"update:progress": {
+		version: string;
+		received: number;
+		total: number;
+	};
 	"update:complete": {
 		previousVersion: string;
 		newVersion: string;
@@ -4382,11 +4428,13 @@ export declare class RequireTestError extends Error {
 	constructor(configName: string);
 }
 /**
- * Error thrown when attempting destructive operations on protected configs.
+ * Error thrown when the config's access policy blocks a destructive
+ * operation — either the role denies it outright, or the role requires
+ * confirmation the SDK cannot provide interactively.
  *
  * @example
  * ```typescript
- * // config.protected is true — all destructive ops are blocked
+ * // config.access.user is 'operator' — db:reset requires confirmation the SDK can't give
  * await ctx.noorm.db.truncate()  // Throws ProtectedConfigError
  * ```
  */
@@ -4394,7 +4442,7 @@ export declare class ProtectedConfigError extends Error {
 	readonly configName: string;
 	readonly operation: string;
 	readonly name: "ProtectedConfigError";
-	constructor(configName: string, operation: string);
+	constructor(configName: string, operation: string, reason?: string);
 }
 /**
  * Create an SDK context for programmatic database access.