@thiagodiogo/pastelsdd 1.0.0-beta.1

package/dist/core/workspace/foundation.d.ts

@@ -0,0 +1,62 @@
+import { type ContextStoreBinding, type ContextStoreSelector } from '../context-store/index.js';
+export declare const WORKSPACE_METADATA_DIR_NAME = ".pastelsdd-workspace";
+export declare const WORKSPACE_VIEW_STATE_FILE_NAME = "workspace.yaml";
+export declare const WORKSPACE_CHANGES_DIR_NAME = "changes";
+export declare const WORKSPACE_CODE_WORKSPACE_EXTENSION = ".code-workspace";
+export declare const WORKSPACE_SUPPORTED_OPENER_VALUES: readonly ["codex", "claude", "github-copilot", "editor"];
+export declare const WORKSPACE_AGENT_OPENER_IDS: readonly ["codex", "claude", "github-copilot"];
+export declare const WORKSPACE_EDITOR_OPENER_IDS: readonly ["vscode"];
+export type WorkspaceSupportedOpenerValue = typeof WORKSPACE_SUPPORTED_OPENER_VALUES[number];
+export type WorkspaceAgentOpenerId = typeof WORKSPACE_AGENT_OPENER_IDS[number];
+export type WorkspaceEditorOpenerId = typeof WORKSPACE_EDITOR_OPENER_IDS[number];
+export type WorkspacePreferredOpener = {
+    kind: 'agent';
+    id: WorkspaceAgentOpenerId;
+} | {
+    kind: 'editor';
+    id: WorkspaceEditorOpenerId;
+};
+export interface WorkspaceContextState {
+    kind: 'initiative';
+    store: ContextStoreBinding;
+    initiative: {
+        id: string;
+    };
+}
+export interface WorkspaceViewState {
+    version: 1;
+    name: string;
+    context: WorkspaceContextState | null;
+    links: Record<string, string | null>;
+    preferred_opener?: WorkspacePreferredOpener;
+    tools?: string[];
+    workspace_skills?: WorkspaceSkillState;
+}
+export interface WorkspaceSkillState {
+    selected_agents: string[];
+    last_applied_profile?: 'core' | 'custom';
+    last_applied_delivery?: 'both' | 'skills' | 'commands';
+    last_applied_workflow_ids?: string[];
+    last_applied_at?: string;
+}
+export declare function getWorkspaceMetadataDir(workspaceRoot: string): string;
+export declare function getWorkspaceViewStatePath(workspaceRoot: string): string;
+export declare function getWorkspaceChangesDir(workspaceRoot: string): string;
+export declare function getWorkspaceCodeWorkspaceFileName(workspaceName: string): string;
+export declare function getWorkspaceCodeWorkspacePath(workspaceRoot: string, workspaceName: string): string;
+export declare function getWorkspacePortableIgnorePatterns(workspaceName?: string): string[];
+export declare function validateWorkspaceName(name: string): string;
+export declare function validateWorkspaceLinkName(name: string): string;
+export declare function isValidWorkspaceName(name: string): boolean;
+export declare function isValidWorkspaceLinkName(name: string): boolean;
+export declare function isWorkspaceAgentOpenerId(value: string): value is WorkspaceAgentOpenerId;
+export declare function isWorkspaceSupportedOpenerValue(value: string): value is WorkspaceSupportedOpenerValue;
+export declare function parseWorkspacePreferredOpenerValue(value: string): WorkspacePreferredOpener;
+export declare function validateWorkspacePreferredOpener(opener: WorkspacePreferredOpener): WorkspacePreferredOpener;
+export declare function createWorkspaceInitiativeContext(store: ContextStoreBinding, initiativeId: string): WorkspaceContextState;
+export declare function getWorkspaceContextStoreId(context: WorkspaceContextState): string;
+export declare function getWorkspaceContextStoreSelector(context: WorkspaceContextState): ContextStoreSelector;
+export declare function getWorkspaceContextInitiativeId(context: WorkspaceContextState): string;
+export declare function parseWorkspaceViewState(content: string): WorkspaceViewState;
+export declare function serializeWorkspaceViewState(state: WorkspaceViewState): string;
+//# sourceMappingURL=foundation.d.ts.map

package/dist/core/workspace/foundation.js

@@ -0,0 +1,274 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+import { normalizeContextStoreBinding, } from '../context-store/index.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export const WORKSPACE_METADATA_DIR_NAME = '.pastelsdd-workspace';
+export const WORKSPACE_VIEW_STATE_FILE_NAME = 'workspace.yaml';
+export const WORKSPACE_CHANGES_DIR_NAME = 'changes';
+export const WORKSPACE_CODE_WORKSPACE_EXTENSION = '.code-workspace';
+export const WORKSPACE_SUPPORTED_OPENER_VALUES = [
+    'codex',
+    'claude',
+    'github-copilot',
+    'editor',
+];
+export const WORKSPACE_AGENT_OPENER_IDS = [
+    'codex',
+    'claude',
+    'github-copilot',
+];
+export const WORKSPACE_EDITOR_OPENER_IDS = ['vscode'];
+function joinWorkspacePath(basePath, ...segments) {
+    return FileSystemUtils.joinPath(basePath, ...segments);
+}
+export function getWorkspaceMetadataDir(workspaceRoot) {
+    return joinWorkspacePath(workspaceRoot, WORKSPACE_METADATA_DIR_NAME);
+}
+export function getWorkspaceViewStatePath(workspaceRoot) {
+    return joinWorkspacePath(workspaceRoot, WORKSPACE_VIEW_STATE_FILE_NAME);
+}
+export function getWorkspaceChangesDir(workspaceRoot) {
+    return joinWorkspacePath(workspaceRoot, WORKSPACE_CHANGES_DIR_NAME);
+}
+export function getWorkspaceCodeWorkspaceFileName(workspaceName) {
+    validateWorkspaceName(workspaceName);
+    return `${workspaceName}${WORKSPACE_CODE_WORKSPACE_EXTENSION}`;
+}
+export function getWorkspaceCodeWorkspacePath(workspaceRoot, workspaceName) {
+    return joinWorkspacePath(workspaceRoot, getWorkspaceCodeWorkspaceFileName(workspaceName));
+}
+export function getWorkspacePortableIgnorePatterns(workspaceName) {
+    return workspaceName ? [getWorkspaceCodeWorkspaceFileName(workspaceName)] : [];
+}
+function validateFolderStyleName(name, label) {
+    if (name.length === 0) {
+        throw new Error(`${label} must not be empty`);
+    }
+    if (name === '.' || name === '..') {
+        throw new Error(`${label} must not be '${name}'`);
+    }
+    if (/[\\/]/u.test(name)) {
+        throw new Error(`${label} must not contain path separators`);
+    }
+    return name;
+}
+export function validateWorkspaceName(name) {
+    validateFolderStyleName(name, 'Workspace name');
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name)) {
+        throw new Error('Workspace name must be kebab-case with lowercase letters, numbers, and single hyphen separators');
+    }
+    return name;
+}
+export function validateWorkspaceLinkName(name) {
+    return validateFolderStyleName(name, 'Workspace link name');
+}
+export function isValidWorkspaceName(name) {
+    try {
+        validateWorkspaceName(name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isValidWorkspaceLinkName(name) {
+    try {
+        validateWorkspaceLinkName(name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const ContextStoreSelectorSchema = z.union([
+    z
+        .object({
+        kind: z.literal('registry'),
+        id: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal('path'),
+        path: z.string(),
+        observed_id: z.string().optional(),
+    })
+        .strict(),
+]);
+const ContextStoreBindingSchema = z
+    .object({
+    id: z.string(),
+    selector: ContextStoreSelectorSchema,
+})
+    .strict();
+const WorkspaceInitiativeContextSchema = z
+    .object({
+    kind: z.literal('initiative'),
+    store: ContextStoreBindingSchema,
+    initiative: z
+        .object({
+        id: z.string(),
+    })
+        .strict(),
+})
+    .strict();
+const WorkspaceContextSchema = WorkspaceInitiativeContextSchema;
+const WorkspaceSkillStateSchema = z
+    .object({
+    selected_agents: z.array(z.string()),
+    last_applied_profile: z.enum(['core', 'custom']).optional(),
+    last_applied_delivery: z.enum(['both', 'skills', 'commands']).optional(),
+    last_applied_workflow_ids: z.array(z.string()).optional(),
+    last_applied_at: z.string().optional(),
+})
+    .strict();
+const PreferredOpenerSchema = z
+    .object({
+    kind: z.enum(['agent', 'editor']),
+    id: z.string(),
+})
+    .strict();
+const ViewStateSchema = z
+    .object({
+    version: z.literal(1),
+    name: z.string(),
+    context: WorkspaceContextSchema.nullable(),
+    links: z.record(z.string(), z.string().nullable()),
+    preferred_opener: PreferredOpenerSchema.optional(),
+    tools: z.array(z.string()).optional(),
+    workspace_skills: WorkspaceSkillStateSchema.optional(),
+})
+    .strict();
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const location = issue.path.length > 0 ? issue.path.join('.') : 'root';
+        return `${location}: ${issue.message}`;
+    })
+        .join('; ');
+}
+function parseYamlObject(content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${label}: ${message}`);
+    }
+}
+function assertValidMapKeys(keys, validator, label) {
+    for (const key of keys) {
+        try {
+            validator(key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid ${label} '${key}': ${message}`);
+        }
+    }
+}
+function formatSupportedOpenerValues() {
+    return WORKSPACE_SUPPORTED_OPENER_VALUES.join(', ');
+}
+export function isWorkspaceAgentOpenerId(value) {
+    return WORKSPACE_AGENT_OPENER_IDS.includes(value);
+}
+export function isWorkspaceSupportedOpenerValue(value) {
+    return WORKSPACE_SUPPORTED_OPENER_VALUES.includes(value);
+}
+export function parseWorkspacePreferredOpenerValue(value) {
+    if (value === 'editor') {
+        return {
+            kind: 'editor',
+            id: 'vscode',
+        };
+    }
+    if (isWorkspaceAgentOpenerId(value)) {
+        return {
+            kind: 'agent',
+            id: value,
+        };
+    }
+    throw new Error(`Unsupported workspace opener '${value}'. Supported values: ${formatSupportedOpenerValues()}`);
+}
+export function validateWorkspacePreferredOpener(opener) {
+    if (opener.kind === 'editor' && opener.id === 'vscode') {
+        return opener;
+    }
+    if (opener.kind === 'agent' && isWorkspaceAgentOpenerId(opener.id)) {
+        return opener;
+    }
+    throw new Error(`Unsupported workspace opener '${opener.kind}:${opener.id}'. Supported values: ${formatSupportedOpenerValues()}`);
+}
+function normalizeWorkspaceContextState(context) {
+    return createWorkspaceInitiativeContext(normalizeContextStoreBinding(context.store), context.initiative.id);
+}
+function normalizeOptionalWorkspaceContextState(context) {
+    return context ? normalizeWorkspaceContextState(context) : null;
+}
+export function createWorkspaceInitiativeContext(store, initiativeId) {
+    if (initiativeId.length === 0) {
+        throw new Error('Workspace initiative id must not be empty.');
+    }
+    return {
+        kind: 'initiative',
+        store: normalizeContextStoreBinding(store),
+        initiative: {
+            id: initiativeId,
+        },
+    };
+}
+export function getWorkspaceContextStoreId(context) {
+    return context.store.id;
+}
+export function getWorkspaceContextStoreSelector(context) {
+    return context.store.selector;
+}
+export function getWorkspaceContextInitiativeId(context) {
+    return context.initiative.id;
+}
+export function parseWorkspaceViewState(content) {
+    const raw = parseYamlObject(content, 'workspace state');
+    const result = ViewStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid workspace state: ${formatZodIssues(result.error)}`);
+    }
+    validateWorkspaceName(result.data.name);
+    assertValidMapKeys(Object.keys(result.data.links), validateWorkspaceLinkName, 'workspace link name');
+    const preferredOpener = result.data.preferred_opener
+        ? validateWorkspacePreferredOpener(result.data.preferred_opener)
+        : undefined;
+    return {
+        version: 1,
+        name: result.data.name,
+        context: normalizeOptionalWorkspaceContextState(result.data.context),
+        links: result.data.links,
+        ...(preferredOpener ? { preferred_opener: preferredOpener } : {}),
+        ...(result.data.tools ? { tools: result.data.tools } : {}),
+        ...(result.data.workspace_skills
+            ? { workspace_skills: result.data.workspace_skills }
+            : {}),
+    };
+}
+export function serializeWorkspaceViewState(state) {
+    validateWorkspaceName(state.name);
+    assertValidMapKeys(Object.keys(state.links), validateWorkspaceLinkName, 'workspace link name');
+    for (const [linkName, localPath] of Object.entries(state.links)) {
+        if (localPath !== null && typeof localPath !== 'string') {
+            throw new Error(`Invalid workspace link '${linkName}': path must be a string or null`);
+        }
+    }
+    const preferredOpener = state.preferred_opener
+        ? validateWorkspacePreferredOpener(state.preferred_opener)
+        : undefined;
+    return stringifyYaml({
+        version: 1,
+        name: state.name,
+        context: state.context ? normalizeWorkspaceContextState(state.context) : null,
+        links: state.links,
+        ...(preferredOpener ? { preferred_opener: preferredOpener } : {}),
+        ...(state.tools ? { tools: state.tools } : {}),
+        ...(state.workspace_skills ? { workspace_skills: state.workspace_skills } : {}),
+    });
+}
+//# sourceMappingURL=foundation.js.map

package/dist/core/workspace/index.d.ts

@@ -0,0 +1,8 @@
+export * from './foundation.js';
+export * from './link-input.js';
+export * from './openers.js';
+export * from './open-surface.js';
+export * from './registry.js';
+export * from './skills.js';
+export * from './state-io.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/workspace/index.js

@@ -0,0 +1,8 @@
+export * from './foundation.js';
+export * from './link-input.js';
+export * from './openers.js';
+export * from './open-surface.js';
+export * from './registry.js';
+export * from './skills.js';
+export * from './state-io.js';
+//# sourceMappingURL=index.js.map

package/dist/core/workspace/legacy-state.d.ts

@@ -0,0 +1,28 @@
+import { type WorkspaceContextState, type WorkspacePreferredOpener, type WorkspaceSkillState, type WorkspaceViewState } from './foundation.js';
+export declare const WORKSPACE_LEGACY_SHARED_STATE_FILE_NAME = "workspace.yaml";
+export declare const WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME = "local.yaml";
+export declare const WORKSPACE_LEGACY_LOCAL_STATE_IGNORE_PATTERN = ".pastelsdd-workspace/local.yaml";
+export type WorkspaceLinkState = Record<string, unknown>;
+export interface WorkspaceSharedState {
+    version: 1;
+    name: string;
+    context: WorkspaceContextState | null;
+    links: Record<string, WorkspaceLinkState>;
+}
+export interface WorkspaceLocalState {
+    version: 1;
+    paths: Record<string, string>;
+    preferred_opener?: WorkspacePreferredOpener;
+    tools?: string[];
+    workspace_skills?: WorkspaceSkillState;
+}
+export declare function getWorkspaceLegacySharedStatePath(workspaceRoot: string): string;
+export declare function getWorkspaceLegacyLocalStatePath(workspaceRoot: string): string;
+export declare function workspaceViewToSharedState(state: WorkspaceViewState): WorkspaceSharedState;
+export declare function workspaceViewToLocalState(state: WorkspaceViewState): WorkspaceLocalState;
+export declare function workspaceStatePartsToViewState(sharedState: WorkspaceSharedState, localState: WorkspaceLocalState | null): WorkspaceViewState;
+export declare function parseWorkspaceSharedState(content: string): WorkspaceSharedState;
+export declare function parseWorkspaceLocalState(content: string): WorkspaceLocalState;
+export declare function serializeWorkspaceSharedState(state: WorkspaceSharedState): string;
+export declare function serializeWorkspaceLocalState(state: WorkspaceLocalState): string;
+//# sourceMappingURL=legacy-state.d.ts.map

package/dist/core/workspace/legacy-state.js

@@ -0,0 +1,200 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+import { WORKSPACE_METADATA_DIR_NAME, WORKSPACE_VIEW_STATE_FILE_NAME, getWorkspaceMetadataDir, parseWorkspaceViewState, validateWorkspaceLinkName, validateWorkspaceName, validateWorkspacePreferredOpener, } from './foundation.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export const WORKSPACE_LEGACY_SHARED_STATE_FILE_NAME = WORKSPACE_VIEW_STATE_FILE_NAME;
+export const WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME = 'local.yaml';
+export const WORKSPACE_LEGACY_LOCAL_STATE_IGNORE_PATTERN = `${WORKSPACE_METADATA_DIR_NAME}/${WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME}`;
+function joinWorkspacePath(basePath, ...segments) {
+    return FileSystemUtils.joinPath(basePath, ...segments);
+}
+export function getWorkspaceLegacySharedStatePath(workspaceRoot) {
+    return joinWorkspacePath(getWorkspaceMetadataDir(workspaceRoot), WORKSPACE_LEGACY_SHARED_STATE_FILE_NAME);
+}
+export function getWorkspaceLegacyLocalStatePath(workspaceRoot) {
+    return joinWorkspacePath(getWorkspaceMetadataDir(workspaceRoot), WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const PlainObjectSchema = z.custom(isPlainObject, {
+    message: 'must be an object',
+});
+const PreferredOpenerSchema = z
+    .object({
+    kind: z.enum(['agent', 'editor']),
+    id: z.string(),
+})
+    .strict();
+const WorkspaceSkillStateSchema = z
+    .object({
+    selected_agents: z.array(z.string()),
+    last_applied_profile: z.enum(['core', 'custom']).optional(),
+    last_applied_delivery: z.enum(['both', 'skills', 'commands']).optional(),
+    last_applied_workflow_ids: z.array(z.string()).optional(),
+    last_applied_at: z.string().optional(),
+})
+    .strict();
+const SharedStateSchema = z.object({
+    version: z.literal(1),
+    name: z.string(),
+    context: z.unknown().optional(),
+    links: z.record(z.string(), PlainObjectSchema),
+}).strict();
+const LocalStateSchema = z.object({
+    version: z.literal(1),
+    paths: z.record(z.string(), z.string()),
+    preferred_opener: PreferredOpenerSchema.optional(),
+    tools: z.array(z.string()).optional(),
+    workspace_skills: WorkspaceSkillStateSchema.optional(),
+}).strict();
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const location = issue.path.length > 0 ? issue.path.join('.') : 'root';
+        return `${location}: ${issue.message}`;
+    })
+        .join('; ');
+}
+function parseYamlObject(content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${label}: ${message}`);
+    }
+}
+function assertValidMapKeys(keys, validator, label) {
+    for (const key of keys) {
+        try {
+            validator(key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid ${label} '${key}': ${message}`);
+        }
+    }
+}
+function normalizeLegacyWorkspaceContext(name, context) {
+    return parseWorkspaceViewState(stringifyYaml({
+        version: 1,
+        name,
+        context: context ?? null,
+        links: {},
+    })).context;
+}
+export function workspaceViewToSharedState(state) {
+    return {
+        version: 1,
+        name: state.name,
+        context: state.context,
+        links: Object.fromEntries(Object.keys(state.links).map((linkName) => [linkName, {}])),
+    };
+}
+export function workspaceViewToLocalState(state) {
+    return {
+        version: 1,
+        paths: Object.fromEntries(Object.entries(state.links).filter((entry) => typeof entry[1] === 'string')),
+        ...(state.preferred_opener ? { preferred_opener: state.preferred_opener } : {}),
+        ...(state.tools ? { tools: state.tools } : {}),
+        ...(state.workspace_skills ? { workspace_skills: state.workspace_skills } : {}),
+    };
+}
+export function workspaceStatePartsToViewState(sharedState, localState) {
+    const linkNames = new Set([
+        ...Object.keys(sharedState.links),
+        ...Object.keys(localState?.paths ?? {}),
+    ]);
+    const links = Object.fromEntries([...linkNames]
+        .sort((a, b) => a.localeCompare(b))
+        .map((linkName) => [linkName, localState?.paths[linkName] ?? null]));
+    return {
+        version: 1,
+        name: sharedState.name,
+        context: sharedState.context,
+        links,
+        ...(localState?.preferred_opener ? { preferred_opener: localState.preferred_opener } : {}),
+        ...(localState?.tools ? { tools: localState.tools } : {}),
+        ...(localState?.workspace_skills ? { workspace_skills: localState.workspace_skills } : {}),
+    };
+}
+export function parseWorkspaceSharedState(content) {
+    const raw = parseYamlObject(content, 'workspace shared state');
+    try {
+        return workspaceViewToSharedState(parseWorkspaceViewState(content));
+    }
+    catch {
+        // Fall through to the legacy shared schema.
+    }
+    const result = SharedStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid workspace shared state: ${formatZodIssues(result.error)}`);
+    }
+    validateWorkspaceName(result.data.name);
+    assertValidMapKeys(Object.keys(result.data.links), validateWorkspaceLinkName, 'workspace link name');
+    return {
+        version: 1,
+        name: result.data.name,
+        context: normalizeLegacyWorkspaceContext(result.data.name, result.data.context),
+        links: result.data.links,
+    };
+}
+export function parseWorkspaceLocalState(content) {
+    const raw = parseYamlObject(content, 'workspace local state');
+    try {
+        return workspaceViewToLocalState(parseWorkspaceViewState(content));
+    }
+    catch {
+        // Fall through to the legacy local schema.
+    }
+    const result = LocalStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid workspace local state: ${formatZodIssues(result.error)}`);
+    }
+    assertValidMapKeys(Object.keys(result.data.paths), validateWorkspaceLinkName, 'workspace local path name');
+    const preferredOpener = result.data.preferred_opener
+        ? validateWorkspacePreferredOpener(result.data.preferred_opener)
+        : undefined;
+    return {
+        version: 1,
+        paths: result.data.paths,
+        ...(preferredOpener ? { preferred_opener: preferredOpener } : {}),
+        ...(result.data.tools ? { tools: result.data.tools } : {}),
+        ...(result.data.workspace_skills ? { workspace_skills: result.data.workspace_skills } : {}),
+    };
+}
+export function serializeWorkspaceSharedState(state) {
+    validateWorkspaceName(state.name);
+    assertValidMapKeys(Object.keys(state.links), validateWorkspaceLinkName, 'workspace link name');
+    for (const [linkName, linkState] of Object.entries(state.links)) {
+        if (!isPlainObject(linkState)) {
+            throw new Error(`Invalid workspace link '${linkName}': link state must be an object`);
+        }
+    }
+    return stringifyYaml({
+        version: 1,
+        name: state.name,
+        context: state.context,
+        links: state.links,
+    });
+}
+export function serializeWorkspaceLocalState(state) {
+    assertValidMapKeys(Object.keys(state.paths), validateWorkspaceLinkName, 'workspace local path name');
+    for (const [linkName, localPath] of Object.entries(state.paths)) {
+        if (typeof localPath !== 'string') {
+            throw new Error(`Invalid workspace local path '${linkName}': path must be a string`);
+        }
+    }
+    const preferredOpener = state.preferred_opener
+        ? validateWorkspacePreferredOpener(state.preferred_opener)
+        : undefined;
+    return stringifyYaml({
+        version: 1,
+        paths: state.paths,
+        ...(preferredOpener ? { preferred_opener: preferredOpener } : {}),
+        ...(state.tools ? { tools: state.tools } : {}),
+        ...(state.workspace_skills ? { workspace_skills: state.workspace_skills } : {}),
+    });
+}
+//# sourceMappingURL=legacy-state.js.map

package/dist/core/workspace/link-input.d.ts

@@ -0,0 +1,9 @@
+export interface WorkspaceParsedLinkInput {
+    name?: string;
+    pathInput: string;
+}
+export interface WorkspaceLinkInputParseOptions {
+    cwd?: string;
+}
+export declare function parseWorkspaceSetupLinkInput(value: string, options?: WorkspaceLinkInputParseOptions): Promise<WorkspaceParsedLinkInput>;
+//# sourceMappingURL=link-input.d.ts.map

package/dist/core/workspace/link-input.js

@@ -0,0 +1,32 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+const fs = nodeFs.promises;
+async function directoryExists(inputPath, cwd) {
+    if (inputPath.length === 0) {
+        return false;
+    }
+    const resolvedPath = path.isAbsolute(inputPath)
+        ? path.resolve(inputPath)
+        : path.resolve(cwd, inputPath);
+    try {
+        return (await fs.stat(resolvedPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function parseWorkspaceSetupLinkInput(value, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (await directoryExists(value, cwd)) {
+        return { pathInput: value };
+    }
+    const separatorIndex = value.indexOf('=');
+    if (separatorIndex === -1) {
+        return { pathInput: value };
+    }
+    return {
+        name: value.slice(0, separatorIndex),
+        pathInput: value.slice(separatorIndex + 1),
+    };
+}
+//# sourceMappingURL=link-input.js.map

package/dist/core/workspace/open-surface.d.ts

@@ -0,0 +1,43 @@
+import { WorkspaceViewState } from './foundation.js';
+export declare const WORKSPACE_GUIDANCE_START_MARKER = "<!-- PASTELSDD:WORKSPACE-GUIDANCE:START -->";
+export declare const WORKSPACE_GUIDANCE_END_MARKER = "<!-- PASTELSDD:WORKSPACE-GUIDANCE:END -->";
+export declare const WORKSPACE_GUIDANCE_BODY = "# Pastelsdd Workspace Guidance\n\nThis directory is an Pastelsdd workspace: a local working view over context stores, initiatives, repos, and folders.\n\n- Use this workspace to open the local view of coordinated work.\n- Use initiatives for durable cross-team or cross-repo intent, decisions, requirements, and coordination context.\n- Use repo-local Pastelsdd changes for implementation plans owned by a repo or team.\n- Use linked repos and folders to inspect context, understand ownership, and make edits in the place that owns the work.\n- Keep workspace-local files focused on local paths, opener state, agent setup, and other machine-specific view state.\n- Use Pastelsdd workspace commands instead of hand-editing `workspace.yaml`.\n- If this workspace contains legacy or beta workspace-level planning files, treat them as compatibility context unless the user explicitly asks to use that beta flow.";
+export interface WorkspaceOpenResolvedContext {
+    contextStore: {
+        id: string;
+        root: string;
+    };
+    initiative: {
+        id: string;
+        title: string;
+        root: string;
+        metadataPath: string;
+        storePath: string;
+    };
+}
+export interface WorkspaceOpenLink {
+    name: string;
+    path: string;
+}
+export interface WorkspaceSkippedOpenLink {
+    name: string;
+    path: string | null;
+    reason: 'missing-local-path' | 'path-missing';
+}
+export interface WorkspaceOpenSurfaceLinks {
+    links: WorkspaceOpenLink[];
+    skipped: WorkspaceSkippedOpenLink[];
+}
+export interface WorkspaceOpenSurfaceGeneration {
+    agentsPath: string;
+    codeWorkspacePath: string;
+}
+export declare function buildWorkspaceGuidanceBlock(viewState?: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function applyWorkspaceGuidanceBlock(existingContent: string, viewState?: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function buildWorkspaceCodeWorkspaceContent(links: WorkspaceOpenLink[], resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath: string, links: WorkspaceOpenLink[], resolvedContext?: WorkspaceOpenResolvedContext | null): Promise<void>;
+export declare function resolveWorkspaceOpenLinks(viewState: WorkspaceViewState): Promise<WorkspaceOpenSurfaceLinks>;
+export declare function syncWorkspaceOpenSurface(workspaceRoot: string, viewState: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): Promise<WorkspaceOpenSurfaceLinks & {
+    generated: WorkspaceOpenSurfaceGeneration;
+}>;
+//# sourceMappingURL=open-surface.d.ts.map