@sdods/contracts 0.2.0

package/dist/schemas/project.js

@@ -0,0 +1,394 @@
+import { z } from 'zod';
+export const LayerSchema = z.enum(['ui', 'api', 'hybrid', 'recorded']);
+export const BrowserSchema = z.enum([
+    'chromium',
+    'firefox',
+    'webkit',
+    'mobile-chrome',
+    'mobile-safari',
+]);
+export const ShotPolicySchema = z.enum(['off', 'on-failure', 'scenario', 'step', 'visual']);
+export const SlugSchema = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]*$/, 'slug must be lowercase letters, digits and dashes');
+export const DataSourceSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('csv'), path: z.string(), fallback: z.string().optional() }),
+    z.object({ type: z.literal('json'), path: z.string(), fallback: z.string().optional() }),
+    z.object({ type: z.literal('yaml'), path: z.string(), fallback: z.string().optional() }),
+    z.object({ type: z.literal('db'), table: z.string(), envColumn: z.string().default('env') }),
+    z.object({ type: z.literal('openapi'), spec: z.string(), schema: z.string() }),
+]);
+export const UserPoolSchema = z.object({
+    dataset: z.string(),
+    roleColumn: z.string().default('role'),
+    leaseStore: z.enum(['file', 'db']).default('file'),
+    leaseTtlMs: z
+        .number()
+        .int()
+        .positive()
+        .default(10 * 60_000),
+});
+export const AuthStrategySchema = z.enum([
+    'none',
+    'form',
+    'token',
+    'oauth-client-credentials',
+    'sso',
+    'custom',
+]);
+export const AuthFormSchema = z.object({
+    loginPath: z.string().default('/'),
+    usernameSelector: z.string(),
+    passwordSelector: z.string(),
+    submitSelector: z.string(),
+    readySelector: z.string().optional(),
+    readyUrl: z.string().optional(),
+});
+export const ProjectAuthSchema = z.object({
+    strategy: AuthStrategySchema.default('none'),
+    storageState: z.boolean().default(true),
+    maxAgeMinutes: z.number().int().positive().default(60),
+    form: AuthFormSchema.optional(),
+    tokenPlacement: z
+        .object({
+        kind: z.enum(['localStorage', 'cookie', 'header']).default('header'),
+        name: z.string().default('Authorization'),
+        prefix: z.string().default('Bearer '),
+    })
+        .optional(),
+});
+export const ScreenshotConfigSchema = z.object({
+    policy: z.record(z.string(), ShotPolicySchema).default({ default: 'on-failure' }),
+    fullPage: z.boolean().default(false),
+    mask: z.array(z.string()).default([]),
+    viewport: z
+        .object({ width: z.number().int().positive(), height: z.number().int().positive() })
+        .default({ width: 1280, height: 720 }),
+    onlyOnFailure: z.boolean().default(false),
+});
+export const HealConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    primaryTimeoutMs: z.number().int().positive().default(3000),
+    probeTimeoutMs: z.number().int().positive().default(1500),
+    minScore: z.number().min(0).max(1).default(0.6),
+    actions: z
+        .array(z.enum(['click', 'fill', 'select', 'assert', 'hover', 'check']))
+        .default(['click', 'fill', 'select', 'assert', 'hover', 'check']),
+});
+export const TimeoutsSchema = z.object({
+    test: z.number().int().positive().default(60_000),
+    expect: z.number().int().positive().default(10_000),
+    action: z.number().int().positive().default(15_000),
+    navigation: z.number().int().positive().default(30_000),
+    api: z.number().int().positive().default(15_000),
+});
+export const RetriesSchema = z.object({
+    ci: z.number().int().min(0).default(2),
+    local: z.number().int().min(0).default(0),
+    byTag: z.record(z.string(), z.number().int().min(0)).default({}),
+});
+export const PerfBudgetsSchema = z.object({
+    pageLoadMs: z.number().positive().optional(),
+    lcpMs: z.number().positive().optional(),
+    fcpMs: z.number().positive().optional(),
+    ttfbMs: z.number().positive().optional(),
+    apiP95Ms: z.number().positive().optional(),
+});
+export const GitHubIntegrationSchema = z.object({
+    enabled: z.boolean().default(false),
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    checkRun: z.boolean().default(true),
+    prComment: z.boolean().default(true),
+    createIssueOnFailure: z.enum(['never', 'smoke', 'always']).default('never'),
+    closeOnPass: z.boolean().default(false),
+    labels: z.array(z.string()).default(['sdods']),
+    tokenEnv: z.string().default('GITHUB_TOKEN'),
+    uploadToRelease: z.string().optional(),
+});
+export const JiraIntegrationSchema = z.object({
+    enabled: z.boolean().default(false),
+    baseUrl: z.string().url().optional(),
+    projectKey: z.string().optional(),
+    issueType: z.string().default('Bug'),
+    authMode: z.enum(['basic', 'bearer']).default('basic'),
+    emailEnv: z.string().default('JIRA_EMAIL'),
+    tokenEnv: z.string().default('JIRA_API_TOKEN'),
+    createIssueOnFailure: z.enum(['never', 'smoke', 'always']).default('never'),
+    transitionOnPass: z.string().optional(),
+    linkTaggedScenarios: z.boolean().default(true),
+    labels: z.array(z.string()).default(['sdods']),
+    maxAttachmentMb: z.number().positive().default(10),
+});
+export const IntegrationsSchema = z.object({
+    github: GitHubIntegrationSchema.optional(),
+    jira: JiraIntegrationSchema.optional(),
+    custom: z
+        .array(z.object({ module: z.string(), options: z.record(z.string(), z.unknown()).optional() }))
+        .default([]),
+});
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+export const McpServerSchema = z.discriminatedUnion('transport', [
+    z.object({
+        transport: z.literal('stdio'),
+        command: z.string(),
+        args: z.array(z.string()).default([]),
+        envFrom: z
+            .record(z.string(), z.string().regex(ENV_NAME, 'must be an env var NAME'))
+            .default({}),
+        allowedTools: z.array(z.string()).optional(),
+        enabled: z.boolean().default(true),
+        timeoutMs: z.number().int().positive().default(60_000),
+    }),
+    z.object({
+        transport: z.literal('http'),
+        url: z.string().url(),
+        headersFrom: z
+            .record(z.string(), z.string().regex(ENV_NAME, 'must be an env var NAME'))
+            .default({}),
+        allowedTools: z.array(z.string()).optional(),
+        enabled: z.boolean().default(true),
+        timeoutMs: z.number().int().positive().default(60_000),
+    }),
+]);
+export const McpConfigSchema = z.object({
+    servers: z.record(z.string(), McpServerSchema).default({}),
+});
+/** Settings for a model server you run yourself: Ollama, vLLM, LM Studio, llama.cpp. */
+export const LocalLlmConfigSchema = z
+    .object({
+    /** Ollama's native endpoint, or the OpenAI-compatible base URL of another server. */
+    baseUrl: z.string().url().optional(),
+    /**
+     * `options.num_ctx`. Ollama loads a model at 4096 tokens whatever its weights allow, and
+     * truncates a longer prompt without saying so, so this is the setting that decides whether
+     * an agent job sees its whole prompt.
+     */
+    contextTokens: z.number().int().min(2048).max(1_048_576).optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    /** Local generation is minutes, not seconds. */
+    requestTimeoutMs: z.number().int().positive().default(300_000),
+    /** How long the server keeps the model in memory between turns. */
+    keepAlive: z.string().default('10m'),
+})
+    .default({ requestTimeoutMs: 300_000, keepAlive: '10m' });
+export const AgentsConfigSchema = z.object({
+    /**
+     * claude/openai-compatible use API keys; claude-code/codex shell out to the logged-in CLI;
+     * ollama runs a model on this machine, with no key and no per-token cost.
+     */
+    provider: z
+        .enum(['claude', 'claude-code', 'codex', 'openai-compatible', 'ollama', 'fake'])
+        .optional(),
+    /**
+     * How much of the platform a model is shown. `auto` picks `small` for a local or small model:
+     * a handful of tools, one call per turn, and the project's real step patterns in the prompt.
+     */
+    profile: z.enum(['auto', 'full', 'small']).default('auto'),
+    models: z.record(z.string(), z.string()).default({}),
+    maxTurns: z.record(z.string(), z.number().int().positive()).default({}),
+    budgetUsd: z.record(z.string(), z.number().positive()).default({ default: 2 }),
+    maxRunsPerJob: z.number().int().positive().default(3),
+    sourceRoots: z.array(z.string()).default([]),
+    local: LocalLlmConfigSchema,
+});
+export const ScheduleSchema = z.object({
+    name: z.string(),
+    cron: z.string(),
+    timezone: z.string().default('UTC'),
+    env: z.string().optional(),
+    tags: z.string().optional(),
+    layers: z.array(LayerSchema).optional(),
+    browsers: z.array(BrowserSchema).optional(),
+    workers: z.number().int().positive().optional(),
+    harMode: z.enum(['off', 'update', 'replay']).optional(),
+    overlap: z.enum(['skip', 'queue', 'cancel-previous']).default('skip'),
+    jitterSeconds: z.number().int().min(0).default(0),
+    catchUp: z.boolean().default(false),
+    enabled: z.boolean().default(true),
+    notify: z.array(z.enum(['github', 'jira', 'webhook'])).default([]),
+    retentionRuns: z.number().int().positive().optional(),
+});
+/**
+ * Hierarchy: organization → workspace → project → module.
+ * A module is a feature area of an application (auth, inventory, checkout …) that owns a
+ * features directory, default tags and an owner. A process is a named, repeatable run recipe
+ * (pr-check, nightly-regression, release-gate …) that pins tags/layers/browsers/env and a trigger.
+ */
+export const OrganizationSchema = z.object({
+    slug: SlugSchema,
+    name: z.string().min(1),
+    description: z.string().optional(),
+    url: z.string().url().optional(),
+});
+export const WorkspaceSchema = z.object({
+    slug: SlugSchema,
+    name: z.string().min(1),
+    description: z.string().optional(),
+    organization: SlugSchema.optional(),
+});
+export const TestingTypeSchema = z.enum([
+    'functional',
+    'smoke',
+    'regression',
+    'sanity',
+    'integration',
+    'contract',
+    'visual',
+    'accessibility',
+    'performance',
+    'security',
+    'data-driven',
+    'exploratory',
+]);
+export const ModuleSchema = z.object({
+    name: SlugSchema,
+    title: z.string().optional(),
+    description: z.string().optional(),
+    /** directory under features/ (default: the module name) */
+    path: z.string().optional(),
+    layers: z.array(LayerSchema).optional(),
+    testingTypes: z.array(TestingTypeSchema).default(['functional']),
+    /** tags every scenario in this module is expected to carry (lint warns when missing) */
+    tags: z.array(z.string()).default([]),
+    owner: z.string().optional(),
+    jiraComponent: z.string().optional(),
+    routes: z.array(z.string()).default([]),
+    endpoints: z.array(z.string()).default([]),
+});
+export const ProcessTriggerSchema = z.enum([
+    'manual',
+    'pr',
+    'merge',
+    'nightly',
+    'release',
+    'schedule',
+    'webhook',
+]);
+export const ProcessSchema = z.object({
+    name: SlugSchema,
+    title: z.string().optional(),
+    description: z.string().optional(),
+    trigger: ProcessTriggerSchema.default('manual'),
+    env: z.string().optional(),
+    tags: z.string().optional(),
+    layers: z.array(LayerSchema).optional(),
+    browsers: z.array(BrowserSchema).optional(),
+    modules: z.array(SlugSchema).optional(),
+    workers: z.number().int().positive().optional(),
+    retries: z.number().int().min(0).optional(),
+    harMode: z.enum(['off', 'update', 'replay']).optional(),
+    failOnFlaky: z.boolean().default(false),
+    gates: z
+        .object({
+        minPassRate: z.number().min(0).max(100).optional(),
+        maxFlaky: z.number().int().min(0).optional(),
+        perfBudgets: z.boolean().default(false),
+        a11y: z.boolean().default(false),
+    })
+        .default({ perfBudgets: false, a11y: false }),
+    notify: z.array(z.enum(['github', 'jira', 'webhook'])).default([]),
+    schedule: z.string().optional(),
+});
+export const ProjectConfigSchema = z.object({
+    slug: SlugSchema,
+    name: z.string().min(1),
+    description: z.string().optional(),
+    organization: SlugSchema.optional(),
+    workspace: SlugSchema.optional(),
+    modules: z.array(ModuleSchema).default([]),
+    processes: z.array(ProcessSchema).default([]),
+    layers: z.array(LayerSchema).min(1),
+    browsers: z.array(BrowserSchema).min(1).default(['chromium']),
+    channel: z.enum(['chrome', 'msedge', 'chrome-beta', 'msedge-beta']).optional(),
+    testIdAttribute: z.string().default('data-testid'),
+    routes: z.record(z.string(), z.string()).default({}),
+    tags: z
+        .object({
+        suites: z.array(z.string()).min(1).default(['smoke', 'regression', 'sanity']),
+        extra: z.array(z.string()).default([]),
+        roles: z.array(z.string()).default([]),
+    })
+        .default({ suites: ['smoke', 'regression', 'sanity'], extra: [], roles: [] }),
+    envs: z.object({ default: z.string(), available: z.array(z.string()).min(1) }),
+    data: z
+        .object({
+        sources: z.record(z.string(), DataSourceSchema).default({}),
+        factories: z.string().optional(),
+        userPool: UserPoolSchema.optional(),
+    })
+        .default({ sources: {} }),
+    auth: ProjectAuthSchema.default({ strategy: 'none', storageState: true, maxAgeMinutes: 60 }),
+    screenshots: ScreenshotConfigSchema.default({
+        policy: { default: 'on-failure' },
+        fullPage: false,
+        mask: [],
+        viewport: { width: 1280, height: 720 },
+        onlyOnFailure: false,
+    }),
+    heal: HealConfigSchema.default({
+        enabled: true,
+        primaryTimeoutMs: 3000,
+        probeTimeoutMs: 1500,
+        minScore: 0.6,
+        actions: ['click', 'fill', 'select', 'assert', 'hover', 'check'],
+    }),
+    timeouts: TimeoutsSchema.default({
+        test: 60_000,
+        expect: 10_000,
+        action: 15_000,
+        navigation: 30_000,
+        api: 15_000,
+    }),
+    retries: RetriesSchema.default({ ci: 2, local: 0, byTag: {} }),
+    perf: z.object({ budgets: PerfBudgetsSchema.default({}) }).default({ budgets: {} }),
+    integrations: IntegrationsSchema.default({ custom: [] }),
+    mcp: McpConfigSchema.default({ servers: {} }),
+    agents: AgentsConfigSchema.default({
+        models: {},
+        maxTurns: {},
+        profile: 'auto',
+        budgetUsd: { default: 2 },
+        maxRunsPerJob: 3,
+        sourceRoots: [],
+        local: { requestTimeoutMs: 300_000, keepAlive: '10m' },
+    }),
+    schedules: z.array(ScheduleSchema).default([]),
+    reports: z
+        .object({
+        cucumberHtml: z.boolean().default(false),
+        allure: z.boolean().default(false),
+        junit: z.boolean().default(false),
+    })
+        .default({ cucumberHtml: false, allure: false, junit: false }),
+    /** How the CI matrix (`sdods project list --matrix`) treats this project. */
+    ci: z
+        .object({
+        /** false = excluded from the generic browser matrix (e.g. a project that needs its own server) */
+        enabled: z.boolean().default(true),
+        /** environment the matrix runs against (default: envs.default) */
+        env: z.string().optional(),
+        /** tag expression for the matrix run (default: the workflow's choice) */
+        tags: z.string().optional(),
+        /** browsers to include in the matrix (default: project browsers) */
+        browsers: z.array(BrowserSchema).optional(),
+    })
+        .default({ enabled: true }),
+});
+/** Root `sdods.workspace.yaml`: names the organization and workspace every project in the repo belongs to. */
+export const WorkspaceFileSchema = z.object({
+    organization: OrganizationSchema,
+    /** one organization can hold many workspaces; projects pick one via `workspace:` */
+    workspaces: z.array(WorkspaceSchema).min(1),
+    /** workspace used by projects that do not set `workspace:` */
+    defaultWorkspace: SlugSchema,
+    defaults: z
+        .object({
+        browsers: z.array(BrowserSchema).optional(),
+        suites: z.array(z.string()).optional(),
+        testIdAttribute: z.string().optional(),
+        processes: z.array(ProcessSchema).default([]),
+    })
+        .default({ processes: [] }),
+});
+//# sourceMappingURL=project.js.map

package/dist/scopes.d.ts

@@ -0,0 +1,32 @@
+export declare const SCOPES: readonly ["orgs:read", "orgs:admin", "workspaces:read", "workspaces:write", "projects:read", "projects:write", "envs:read", "envs:write", "datasets:read", "datasets:write", "runs:read", "runs:write", "runs:ingest", "artifacts:read", "features:read", "features:write", "agents:run", "agents:review", "integrations:read", "integrations:write", "schedules:read", "schedules:write", "processes:read", "processes:write", "users:admin", "audit:read"];
+export type Scope = (typeof SCOPES)[number];
+/** Platform-wide roles (a user's baseline). */
+export declare const ROLES: readonly ["viewer", "editor", "admin"];
+export type Role = (typeof ROLES)[number];
+/** Organization membership roles. */
+export declare const ORG_ROLES: readonly ["member", "admin", "owner"];
+export type OrgRole = (typeof ORG_ROLES)[number];
+/** Workspace membership roles. */
+export declare const WORKSPACE_ROLES: readonly ["viewer", "editor", "admin"];
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+export declare const ROLE_SCOPES: Record<Role, readonly Scope[]>;
+/** Org role → implied workspace role for every workspace in that org. */
+export declare const ORG_ROLE_TO_WORKSPACE_ROLE: Record<OrgRole, WorkspaceRole>;
+/**
+ * Effective role inside a workspace = the higher of the explicit workspace membership and the
+ * role implied by the organization membership. Platform admins are admin everywhere.
+ */
+export declare function effectiveWorkspaceRole(input: {
+    platformRole?: Role;
+    orgRole?: OrgRole;
+    workspaceRole?: WorkspaceRole;
+}): WorkspaceRole | null;
+export declare function scopesForRole(role: Role): Scope[];
+export declare function scopesForWorkspaceRole(role: WorkspaceRole): Scope[];
+export declare function isScope(v: string): v is Scope;
+export declare function hasScope(granted: readonly string[], required: Scope): boolean;
+/** Tool access levels map onto scopes so the MCP registry can gate uniformly. */
+export type ToolAccess = 'read' | 'run' | 'write';
+export declare function scopeForToolAccess(access: ToolAccess, domain: string): Scope | null;
+export declare const API_TOKEN_PREFIX = "amx_";
+//# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.js

@@ -0,0 +1,95 @@
+export const SCOPES = [
+    'orgs:read',
+    'orgs:admin',
+    'workspaces:read',
+    'workspaces:write',
+    'projects:read',
+    'projects:write',
+    'envs:read',
+    'envs:write',
+    'datasets:read',
+    'datasets:write',
+    'runs:read',
+    'runs:write',
+    'runs:ingest',
+    'artifacts:read',
+    'features:read',
+    'features:write',
+    'agents:run',
+    'agents:review',
+    'integrations:read',
+    'integrations:write',
+    'schedules:read',
+    'schedules:write',
+    'processes:read',
+    'processes:write',
+    'users:admin',
+    'audit:read',
+];
+/** Platform-wide roles (a user's baseline). */
+export const ROLES = ['viewer', 'editor', 'admin'];
+/** Organization membership roles. */
+export const ORG_ROLES = ['member', 'admin', 'owner'];
+/** Workspace membership roles. */
+export const WORKSPACE_ROLES = ['viewer', 'editor', 'admin'];
+const READ_SCOPES = SCOPES.filter((s) => s.endsWith(':read'));
+export const ROLE_SCOPES = {
+    viewer: [...READ_SCOPES, 'artifacts:read'],
+    editor: [
+        ...READ_SCOPES,
+        'artifacts:read',
+        'runs:write',
+        'runs:ingest',
+        'features:write',
+        'datasets:write',
+        'envs:write',
+        'schedules:write',
+        'processes:write',
+        'agents:run',
+        'agents:review',
+    ],
+    admin: [...SCOPES],
+};
+/** Org role → implied workspace role for every workspace in that org. */
+export const ORG_ROLE_TO_WORKSPACE_ROLE = {
+    member: 'viewer',
+    admin: 'admin',
+    owner: 'admin',
+};
+const ROLE_RANK = { viewer: 0, editor: 1, admin: 2 };
+/**
+ * Effective role inside a workspace = the higher of the explicit workspace membership and the
+ * role implied by the organization membership. Platform admins are admin everywhere.
+ */
+export function effectiveWorkspaceRole(input) {
+    if (input.platformRole === 'admin')
+        return 'admin';
+    const candidates = [];
+    if (input.workspaceRole)
+        candidates.push(input.workspaceRole);
+    if (input.orgRole)
+        candidates.push(ORG_ROLE_TO_WORKSPACE_ROLE[input.orgRole]);
+    if (candidates.length === 0)
+        return null;
+    return candidates.sort((a, b) => ROLE_RANK[b] - ROLE_RANK[a])[0];
+}
+export function scopesForRole(role) {
+    return [...new Set(ROLE_SCOPES[role])];
+}
+export function scopesForWorkspaceRole(role) {
+    // workspace roles map 1:1 onto the platform role scope sets, minus platform-only scopes
+    const base = scopesForRole(role);
+    return base.filter((s) => s !== 'users:admin' && s !== 'orgs:admin');
+}
+export function isScope(v) {
+    return SCOPES.includes(v);
+}
+export function hasScope(granted, required) {
+    return granted.includes(required);
+}
+export function scopeForToolAccess(access, domain) {
+    const candidate = `${domain}:${access === 'read' ? 'read' : 'write'}`;
+    return isScope(candidate) ? candidate : null;
+}
+export const API_TOKEN_PREFIX = 'amx_';
+//# sourceMappingURL=scopes.js.map