synarcx 0.1.0

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

@@ -0,0 +1,79 @@
+export declare const WORKSPACE_METADATA_DIR_NAME = ".synarcx-workspace";
+export declare const WORKSPACE_SHARED_STATE_FILE_NAME = "workspace.yaml";
+export declare const WORKSPACE_LOCAL_STATE_FILE_NAME = "local.yaml";
+export declare const WORKSPACE_CHANGES_DIR_NAME = "changes";
+export declare const MANAGED_WORKSPACES_DIR_NAME = "workspaces";
+export declare const WORKSPACE_REGISTRY_FILE_NAME = "registry.yaml";
+export declare const WORKSPACE_LOCAL_STATE_IGNORE_PATTERN = ".synarcx-workspace/local.yaml";
+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 WorkspaceSharedState {
+    version: 1;
+    name: string;
+    links: Record<string, WorkspaceLinkState>;
+}
+export type WorkspaceLinkState = Record<string, unknown>;
+export interface WorkspaceLocalState {
+    version: 1;
+    paths: Record<string, string>;
+    preferred_opener?: WorkspacePreferredOpener;
+}
+export interface WorkspaceRegistryState {
+    version: 1;
+    workspaces: Record<string, string>;
+}
+export interface WorkspaceRegistryEntry {
+    name: string;
+    workspaceRoot: string;
+}
+export interface WorkspacePathOptions {
+    globalDataDir?: string;
+}
+export declare function getWorkspaceMetadataDir(workspaceRoot: string): string;
+export declare function getWorkspaceSharedStatePath(workspaceRoot: string): string;
+export declare function getWorkspaceLocalStatePath(workspaceRoot: string): string;
+export declare function getWorkspaceChangesDir(workspaceRoot: string): string;
+export declare function getManagedWorkspacesDir(options?: WorkspacePathOptions): string;
+export declare function getManagedWorkspaceRoot(workspaceName: string, options?: WorkspacePathOptions): string;
+export declare function getWorkspaceRegistryPath(options?: WorkspacePathOptions): 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 isWorkspaceRoot(candidateRoot: string): Promise<boolean>;
+export declare function findWorkspaceRoot(startPath?: string): Promise<string | null>;
+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 parseWorkspaceSharedState(content: string): WorkspaceSharedState;
+export declare function parseWorkspaceLocalState(content: string): WorkspaceLocalState;
+export declare function parseWorkspaceRegistryState(content: string): WorkspaceRegistryState;
+export declare function serializeWorkspaceSharedState(state: WorkspaceSharedState): string;
+export declare function serializeWorkspaceLocalState(state: WorkspaceLocalState): string;
+export declare function serializeWorkspaceRegistryState(state: WorkspaceRegistryState): string;
+export declare function listWorkspaceRegistryEntries(registry: WorkspaceRegistryState): WorkspaceRegistryEntry[];
+export declare function readWorkspaceSharedState(workspaceRoot: string): Promise<WorkspaceSharedState>;
+export declare function readWorkspaceLocalState(workspaceRoot: string): Promise<WorkspaceLocalState>;
+export declare function readOptionalWorkspaceLocalState(workspaceRoot: string): Promise<WorkspaceLocalState | null>;
+export declare function writeWorkspaceSharedState(workspaceRoot: string, state: WorkspaceSharedState): Promise<void>;
+export declare function writeWorkspaceLocalState(workspaceRoot: string, state: WorkspaceLocalState): Promise<void>;
+export declare function readWorkspaceRegistryState(options?: WorkspacePathOptions): Promise<WorkspaceRegistryState | null>;
+export declare function writeWorkspaceRegistryState(state: WorkspaceRegistryState, options?: WorkspacePathOptions): Promise<void>;
+export declare function workspaceChangesDirExists(workspaceRoot: string): Promise<boolean>;
+//# sourceMappingURL=foundation.d.ts.map

package/dist/core/workspace/foundation.js

@@ -0,0 +1,367 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z } from 'zod';
+import { getGlobalDataDir } from '../global-config.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+const fs = nodeFs.promises;
+export const WORKSPACE_METADATA_DIR_NAME = '.synarcx-workspace';
+export const WORKSPACE_SHARED_STATE_FILE_NAME = 'workspace.yaml';
+export const WORKSPACE_LOCAL_STATE_FILE_NAME = 'local.yaml';
+export const WORKSPACE_CHANGES_DIR_NAME = 'changes';
+export const MANAGED_WORKSPACES_DIR_NAME = 'workspaces';
+export const WORKSPACE_REGISTRY_FILE_NAME = 'registry.yaml';
+export const WORKSPACE_LOCAL_STATE_IGNORE_PATTERN = `${WORKSPACE_METADATA_DIR_NAME}/${WORKSPACE_LOCAL_STATE_FILE_NAME}`;
+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 getWorkspaceSharedStatePath(workspaceRoot) {
+    return joinWorkspacePath(getWorkspaceMetadataDir(workspaceRoot), WORKSPACE_SHARED_STATE_FILE_NAME);
+}
+export function getWorkspaceLocalStatePath(workspaceRoot) {
+    return joinWorkspacePath(getWorkspaceMetadataDir(workspaceRoot), WORKSPACE_LOCAL_STATE_FILE_NAME);
+}
+export function getWorkspaceChangesDir(workspaceRoot) {
+    return joinWorkspacePath(workspaceRoot, WORKSPACE_CHANGES_DIR_NAME);
+}
+export function getManagedWorkspacesDir(options = {}) {
+    return joinWorkspacePath(options.globalDataDir ?? getGlobalDataDir(), MANAGED_WORKSPACES_DIR_NAME);
+}
+export function getManagedWorkspaceRoot(workspaceName, options = {}) {
+    validateWorkspaceName(workspaceName);
+    return joinWorkspacePath(getManagedWorkspacesDir(options), workspaceName);
+}
+export function getWorkspaceRegistryPath(options = {}) {
+    return joinWorkspacePath(getManagedWorkspacesDir(options), WORKSPACE_REGISTRY_FILE_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
+        ? [WORKSPACE_LOCAL_STATE_IGNORE_PATTERN, getWorkspaceCodeWorkspaceFileName(workspaceName)]
+        : [WORKSPACE_LOCAL_STATE_IGNORE_PATTERN];
+}
+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;
+    }
+}
+async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function isWorkspaceRoot(candidateRoot) {
+    return pathIsFile(getWorkspaceSharedStatePath(candidateRoot));
+}
+async function getSearchStartDirectory(startPath) {
+    const resolvedStart = path.resolve(startPath);
+    try {
+        const stats = await fs.stat(resolvedStart);
+        return stats.isDirectory() ? resolvedStart : path.dirname(resolvedStart);
+    }
+    catch {
+        return resolvedStart;
+    }
+}
+export async function findWorkspaceRoot(startPath = process.cwd()) {
+    let currentDir = await getSearchStartDirectory(startPath);
+    while (true) {
+        if (await isWorkspaceRoot(currentDir)) {
+            return process.platform === 'win32'
+                ? FileSystemUtils.canonicalizeExistingPath(currentDir)
+                : currentDir;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const PlainObjectSchema = z.custom(isPlainObject, {
+    message: 'must be an object',
+});
+const SharedStateSchema = z.object({
+    version: z.literal(1),
+    name: z.string(),
+    links: z.record(z.string(), PlainObjectSchema),
+}).strict();
+const LocalStateSchema = z.object({
+    version: z.literal(1),
+    paths: z.record(z.string(), z.string()),
+    preferred_opener: z
+        .object({
+        kind: z.enum(['agent', 'editor']),
+        id: z.string(),
+    })
+        .strict()
+        .optional(),
+}).strict();
+const RegistryStateSchema = z.object({
+    version: z.literal(1),
+    workspaces: z.record(z.string(), z.string()),
+}).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()}`);
+}
+export function parseWorkspaceSharedState(content) {
+    const raw = parseYamlObject(content, 'workspace shared state');
+    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,
+        links: result.data.links,
+    };
+}
+export function parseWorkspaceLocalState(content) {
+    const raw = parseYamlObject(content, 'workspace local state');
+    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 } : {}),
+    };
+}
+export function parseWorkspaceRegistryState(content) {
+    const raw = parseYamlObject(content, 'workspace registry state');
+    const result = RegistryStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid workspace registry state: ${formatZodIssues(result.error)}`);
+    }
+    assertValidMapKeys(Object.keys(result.data.workspaces), validateWorkspaceName, 'workspace registry name');
+    return {
+        version: 1,
+        workspaces: result.data.workspaces,
+    };
+}
+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,
+        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 } : {}),
+    });
+}
+export function serializeWorkspaceRegistryState(state) {
+    assertValidMapKeys(Object.keys(state.workspaces), validateWorkspaceName, 'workspace registry name');
+    for (const [workspaceName, workspaceRoot] of Object.entries(state.workspaces)) {
+        if (typeof workspaceRoot !== 'string') {
+            throw new Error(`Invalid workspace registry entry '${workspaceName}': path must be a string`);
+        }
+    }
+    return stringifyYaml({
+        version: 1,
+        workspaces: state.workspaces,
+    });
+}
+export function listWorkspaceRegistryEntries(registry) {
+    return Object.entries(registry.workspaces)
+        .map(([name, workspaceRoot]) => ({ name, workspaceRoot }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function readWorkspaceSharedState(workspaceRoot) {
+    return parseWorkspaceSharedState(await fs.readFile(getWorkspaceSharedStatePath(workspaceRoot), 'utf-8'));
+}
+export async function readWorkspaceLocalState(workspaceRoot) {
+    return parseWorkspaceLocalState(await fs.readFile(getWorkspaceLocalStatePath(workspaceRoot), 'utf-8'));
+}
+function isFileNotFoundError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+export async function readOptionalWorkspaceLocalState(workspaceRoot) {
+    try {
+        return await readWorkspaceLocalState(workspaceRoot);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeWorkspaceSharedState(workspaceRoot, state) {
+    await FileSystemUtils.writeFile(getWorkspaceSharedStatePath(workspaceRoot), serializeWorkspaceSharedState(state));
+}
+export async function writeWorkspaceLocalState(workspaceRoot, state) {
+    await FileSystemUtils.writeFile(getWorkspaceLocalStatePath(workspaceRoot), serializeWorkspaceLocalState(state));
+}
+export async function readWorkspaceRegistryState(options = {}) {
+    const registryPath = getWorkspaceRegistryPath(options);
+    if (!(await pathIsFile(registryPath))) {
+        return null;
+    }
+    return parseWorkspaceRegistryState(await fs.readFile(registryPath, 'utf-8'));
+}
+export async function writeWorkspaceRegistryState(state, options = {}) {
+    await FileSystemUtils.writeFile(getWorkspaceRegistryPath(options), serializeWorkspaceRegistryState(state));
+}
+export async function workspaceChangesDirExists(workspaceRoot) {
+    return pathIsDirectory(getWorkspaceChangesDir(workspaceRoot));
+}
+//# sourceMappingURL=foundation.js.map

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

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

package/dist/core/workspace/index.js

@@ -0,0 +1,5 @@
+export * from './foundation.js';
+export * from './link-input.js';
+export * from './openers.js';
+export * from './open-surface.js';
+//# sourceMappingURL=index.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,24 @@
+import { WorkspaceLocalState, WorkspaceSharedState } from './foundation.js';
+export declare const WORKSPACE_GUIDANCE_START_MARKER = "<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->";
+export declare const WORKSPACE_GUIDANCE_END_MARKER = "<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->";
+export declare const WORKSPACE_GUIDANCE_BODY = "# synarcx Workspace Guidance\n\nThis directory is a synarcx workspace for planning across linked repos or folders.\n\n- Use `changes/` for workspace-level planning.\n- Linked repos and folders are available for exploration and planning.\n- Repo or folder visibility supports exploration and planning.\n- Make implementation edits after the user explicitly asks for implementation work.\n- Treat linked repos and folders as the implementation homes for their owned code.\n- Use synarcx workspace commands instead of hand-editing `.synarcx-workspace/*.yaml`.";
+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 declare function buildWorkspaceGuidanceBlock(): string;
+export declare function applyWorkspaceGuidanceBlock(existingContent: string): string;
+export declare function buildWorkspaceCodeWorkspaceContent(links: WorkspaceOpenLink[]): string;
+export declare function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath: string, links: WorkspaceOpenLink[]): Promise<void>;
+export declare function resolveWorkspaceOpenLinks(sharedState: WorkspaceSharedState, localState: WorkspaceLocalState): Promise<WorkspaceOpenSurfaceLinks>;
+export declare function syncWorkspaceOpenSurface(workspaceRoot: string, sharedState: WorkspaceSharedState, localState: WorkspaceLocalState): Promise<WorkspaceOpenSurfaceLinks>;
+//# sourceMappingURL=open-surface.d.ts.map

package/dist/core/workspace/open-surface.js

@@ -0,0 +1,137 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getWorkspaceCodeWorkspacePath, getWorkspacePortableIgnorePatterns, } from './foundation.js';
+const fs = nodeFs.promises;
+export const WORKSPACE_GUIDANCE_START_MARKER = '<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->';
+export const WORKSPACE_GUIDANCE_END_MARKER = '<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->';
+export const WORKSPACE_GUIDANCE_BODY = `# synarcx Workspace Guidance
+
+This directory is a synarcx workspace for planning across linked repos or folders.
+
+- Use \`changes/\` for workspace-level planning.
+- Linked repos and folders are available for exploration and planning.
+- Repo or folder visibility supports exploration and planning.
+- Make implementation edits after the user explicitly asks for implementation work.
+- Treat linked repos and folders as the implementation homes for their owned code.
+- Use synarcx workspace commands instead of hand-editing \`.synarcx-workspace/*.yaml\`.`;
+async function fileExists(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function directoryExists(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function buildWorkspaceGuidanceBlock() {
+    return `${WORKSPACE_GUIDANCE_START_MARKER}
+${WORKSPACE_GUIDANCE_BODY}
+${WORKSPACE_GUIDANCE_END_MARKER}`;
+}
+export function applyWorkspaceGuidanceBlock(existingContent) {
+    const block = buildWorkspaceGuidanceBlock();
+    const startIndex = existingContent.indexOf(WORKSPACE_GUIDANCE_START_MARKER);
+    const endIndex = existingContent.indexOf(WORKSPACE_GUIDANCE_END_MARKER);
+    if (startIndex !== -1 || endIndex !== -1) {
+        if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+            throw new Error('Invalid synarcx workspace guidance marker state in AGENTS.md.');
+        }
+        const before = existingContent.slice(0, startIndex).trimEnd();
+        const after = existingContent
+            .slice(endIndex + WORKSPACE_GUIDANCE_END_MARKER.length)
+            .trimStart();
+        const prefix = before.length > 0 ? `${before}\n\n` : '';
+        const suffix = after.length > 0 ? `\n\n${after.trimEnd()}\n` : '\n';
+        return `${prefix}${block}${suffix}`;
+    }
+    if (existingContent.trim().length === 0) {
+        return `${block}\n`;
+    }
+    return `${existingContent.trimEnd()}\n\n${block}\n`;
+}
+export function buildWorkspaceCodeWorkspaceContent(links) {
+    const folders = [
+        {
+            path: '.',
+        },
+        ...links.map((link) => ({
+            name: link.name,
+            path: link.path,
+        })),
+    ];
+    return `${JSON.stringify({ folders }, null, 2)}\n`;
+}
+export async function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath, links) {
+    await FileSystemUtils.writeFile(codeWorkspacePath, buildWorkspaceCodeWorkspaceContent(links));
+}
+export async function resolveWorkspaceOpenLinks(sharedState, localState) {
+    const links = [];
+    const skipped = [];
+    for (const linkName of Object.keys(sharedState.links).sort((a, b) => a.localeCompare(b))) {
+        const localPath = localState.paths[linkName] ?? null;
+        if (!localPath) {
+            skipped.push({
+                name: linkName,
+                path: null,
+                reason: 'missing-local-path',
+            });
+            continue;
+        }
+        if (!(await directoryExists(localPath))) {
+            skipped.push({
+                name: linkName,
+                path: localPath,
+                reason: 'path-missing',
+            });
+            continue;
+        }
+        links.push({
+            name: linkName,
+            path: localPath,
+        });
+    }
+    return { links, skipped };
+}
+async function syncWorkspaceGuidance(workspaceRoot) {
+    const agentsPath = path.join(workspaceRoot, 'AGENTS.md');
+    const existingContent = (await fileExists(agentsPath))
+        ? await fs.readFile(agentsPath, 'utf-8')
+        : '';
+    await FileSystemUtils.writeFile(agentsPath, applyWorkspaceGuidanceBlock(existingContent));
+}
+async function syncWorkspaceCodeWorkspace(workspaceRoot, sharedState, links) {
+    await writeWorkspaceCodeWorkspaceFile(getWorkspaceCodeWorkspacePath(workspaceRoot, sharedState.name), links);
+}
+async function syncWorkspaceIgnoreRules(workspaceRoot, workspaceName) {
+    const gitignorePath = path.join(workspaceRoot, '.gitignore');
+    const patterns = getWorkspacePortableIgnorePatterns(workspaceName);
+    const existingContent = (await fileExists(gitignorePath))
+        ? await fs.readFile(gitignorePath, 'utf-8')
+        : '';
+    const existingLines = new Set(existingContent
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0));
+    const missingPatterns = patterns.filter((pattern) => !existingLines.has(pattern));
+    if (missingPatterns.length === 0) {
+        return;
+    }
+    const prefix = existingContent.length > 0 && !existingContent.endsWith('\n') ? '\n' : '';
+    await FileSystemUtils.writeFile(gitignorePath, `${existingContent}${prefix}${missingPatterns.join('\n')}\n`);
+}
+export async function syncWorkspaceOpenSurface(workspaceRoot, sharedState, localState) {
+    const openLinks = await resolveWorkspaceOpenLinks(sharedState, localState);
+    await syncWorkspaceGuidance(workspaceRoot);
+    await syncWorkspaceCodeWorkspace(workspaceRoot, sharedState, openLinks.links);
+    await syncWorkspaceIgnoreRules(workspaceRoot, sharedState.name);
+    return openLinks;
+}
+//# sourceMappingURL=open-surface.js.map