@relayfile/adapter-linear 0.1.21 → 0.2.0

package/dist/layout-prompt.js

@@ -0,0 +1,45 @@
+export const LINEAR_LAYOUT_PROMPT = `# Linear Mount Layout
+
+Always run \`ls\` before constructing a path. PR 0 standardizes human-readable leaf names to \`<sanitized-name>__<id>\`, so consumers should inspect the live directory instead of guessing a filename.
+
+## Tree
+
+\`/linear/LAYOUT.md\` is this guide.
+\`/linear/issues/\`, \`/linear/comments/\`, \`/linear/users/\`, and \`/linear/teams/\` each own their canonical JSON records plus a sibling \`_index.json\`.
+Other integration-owned trees include \`/linear/projects/\`, \`/linear/cycles/\`, \`/linear/milestones/\`, and \`/linear/roadmaps/\`.
+
+## Indexes
+
+\`/linear/issues/_index.json\` rows use:
+
+\`\`\`json
+{ "id": "<id>", "title": "<human-readable>", "updated": "<iso8601>", "identifier": "<TEAM-123>", "state": "<state name>" }
+\`\`\`
+
+\`/linear/comments/_index.json\`, \`/linear/users/_index.json\`, and \`/linear/teams/_index.json\` use:
+
+\`\`\`json
+{ "id": "<id>", "title": "<human-readable>", "updated": "<iso8601>" }
+\`\`\`
+
+## JSONL And Querying
+
+Linear does not emit JSONL in this adapter today. Comments are individual \`.json\` records rather than \`comments.jsonl\`.
+
+Examples:
+
+\`\`\`bash
+ls /linear/issues
+jq '.[0]' /linear/issues/_index.json
+jq '.[] | {identifier, state, title}' /linear/issues/_index.json
+grep -R "ENG-" /linear/comments
+\`\`\`
+`;
+export function linearLayoutPromptFile() {
+    return {
+        path: '/linear/LAYOUT.md',
+        contentType: 'text/markdown; charset=utf-8',
+        content: LINEAR_LAYOUT_PROMPT.endsWith('\n') ? LINEAR_LAYOUT_PROMPT : `${LINEAR_LAYOUT_PROMPT}\n`,
+    };
+}
+//# sourceMappingURL=layout-prompt.js.map

package/dist/layout-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-prompt.js","sourceRoot":"","sources":["../src/layout-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCnC,CAAC;AAEF,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,8BAAuC;QACpD,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,GAAG,oBAAoB,IAAI;KAClG,CAAC;AACJ,CAAC"}

package/dist/linear-adapter.d.ts

@@ -42,9 +42,17 @@ export interface DeleteFileInput {
     workspaceId: string;
     path: string;
 }
+export interface ReadFileInput {
+    workspaceId: string;
+    path: string;
+}
+export interface ReadFileResult {
+    content?: string;
+}
 export interface RelayFileClientLike {
     writeFile(input: WriteFileInput): Promise<WriteFileResult | void>;
     deleteFile?(input: DeleteFileInput): Promise<void> | void;
+    readFile?(inputOrWorkspaceId: ReadFileInput | string, path?: string): Promise<ReadFileResult | string | undefined> | ReadFileResult | string | undefined;
 }
 export declare abstract class IntegrationAdapter {
     protected readonly client: RelayFileClientLike;
@@ -69,5 +77,8 @@ export declare class LinearAdapter extends IntegrationAdapter {
     private normalizeEvent;
     private isRemoveEvent;
     private renderContent;
+    private writeAuxiliaryFiles;
+    private readIndexRows;
+    private recordAuxiliaryWrite;
 }
 //# sourceMappingURL=linear-adapter.d.ts.map

package/dist/linear-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear-adapter.d.ts","sourceRoot":"","sources":["../src/linear-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"linear-adapter.d.ts","sourceRoot":"","sources":["../src/linear-adapter.ts"],"names":[],"mappings":"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"}

package/dist/linear-adapter.js

@@ -1,4 +1,7 @@
-import { computeLinearPath, linearCyclePath, linearIssuePath, linearMilestonePath, linearProjectPath, linearRoadmapPath, linearTeamPath, linearUserPath, normalizeLinearObjectType, } from './path-mapper.js';
+import { computeLinearPath, LINEAR_PATH_ROOT, linearByIdAliasPath, linearByTitleAliasPath, linearCyclePath, linearIssueByStatePath, linearIssuePath, linearMilestonePath, linearProjectPath, linearRoadmapPath, linearTeamPath, linearUserPath, normalizeLinearObjectType, } from './path-mapper.js';
+import { buildLinearIndexFile } from './index-emitter.js';
+import { linearLayoutPromptFile } from './layout-prompt.js';
+import { getLinearCommentHumanReadable, getLinearIssueHumanReadable, linearCommentIndexRow, linearIssueIndexRow, linearTeamIndexRow, linearUserIndexRow, } from './queries.js';
 import { LINEAR_WEBHOOK_OBJECT_TYPES } from './types.js';
 export class IntegrationAdapter {
     client;
@@ -29,16 +32,35 @@ export class LinearAdapter extends IntegrationAdapter {
     async ingestWebhook(workspaceId, event) {
         try {
             const normalized = this.normalizeEvent(event);
-            const path = computeLinearPath(normalized.objectType, normalized.objectId, readIssueTitle(normalized.objectType, normalized.payload));
+            const path = computeLinearPath(normalized.objectType, normalized.objectId, readPathHumanReadable(normalized.objectType, normalized.payload));
+            const content = this.renderContent(workspaceId, normalized, false);
+            const semantics = this.computeSemantics(normalized.objectType, normalized.objectId, normalized.payload);
+            const aliasErrorPath = inferIssueStateAliasErrorPath(normalized);
             if (this.isRemoveEvent(normalized)) {
+                const deletePaths = [path];
+                let filesDeleted = 0;
+                let filesWritten = 0;
+                let filesUpdated = 0;
+                const aliasPath = resolveIssueStateAliasPath(normalized.payload);
+                const previousAliasPath = resolvePreviousIssueStateAliasPath(normalized.payload);
                 if (this.client.deleteFile) {
                     await this.client.deleteFile({ workspaceId, path });
+                    filesDeleted += 1;
+                    for (const candidatePath of uniqueStrings([aliasPath, previousAliasPath])) {
+                        if (!candidatePath) {
+                            continue;
+                        }
+                        await this.client.deleteFile({ workspaceId, path: candidatePath });
+                        deletePaths.push(candidatePath);
+                        filesDeleted += 1;
+                    }
+                    const auxiliary = await this.writeAuxiliaryFiles(workspaceId, normalized, true);
                     return {
-                        filesWritten: 0,
-                        filesUpdated: 0,
-                        filesDeleted: 1,
-                        paths: [path],
-                        errors: [],
+                        filesWritten: filesWritten + auxiliary.filesWritten,
+                        filesUpdated: filesUpdated + auxiliary.filesUpdated,
+                        filesDeleted,
+                        paths: [...deletePaths, ...auxiliary.paths],
+                        errors: auxiliary.errors,
                     };
                 }
                 const deleteResult = await this.client.writeFile({
@@ -46,32 +68,99 @@ export class LinearAdapter extends IntegrationAdapter {
                     path,
                     content: this.renderContent(workspaceId, normalized, true),
                     contentType: JSON_CONTENT_TYPE,
-                    semantics: this.computeSemantics(normalized.objectType, normalized.objectId, normalized.payload),
+                    semantics,
                 });
                 const counts = inferWriteCounts(normalized, deleteResult, true);
+                filesDeleted += counts.filesDeleted;
+                filesWritten += counts.filesWritten;
+                filesUpdated += counts.filesUpdated;
+                for (const candidatePath of uniqueStrings([aliasPath, previousAliasPath])) {
+                    if (!candidatePath) {
+                        continue;
+                    }
+                    const aliasDeleteResult = await this.client.writeFile({
+                        workspaceId,
+                        path: candidatePath,
+                        content: this.renderContent(workspaceId, normalized, true),
+                        contentType: JSON_CONTENT_TYPE,
+                        semantics,
+                    });
+                    const aliasCounts = inferWriteCounts(normalized, aliasDeleteResult, true);
+                    deletePaths.push(candidatePath);
+                    filesDeleted += aliasCounts.filesDeleted;
+                    filesWritten += aliasCounts.filesWritten;
+                    filesUpdated += aliasCounts.filesUpdated;
+                }
+                const auxiliary = await this.writeAuxiliaryFiles(workspaceId, normalized, true);
                 return {
-                    filesWritten: counts.filesWritten,
-                    filesUpdated: counts.filesUpdated,
-                    filesDeleted: counts.filesDeleted,
-                    paths: [path],
-                    errors: [],
+                    filesWritten: filesWritten + auxiliary.filesWritten,
+                    filesUpdated: filesUpdated + auxiliary.filesUpdated,
+                    filesDeleted,
+                    paths: [...deletePaths, ...auxiliary.paths],
+                    errors: auxiliary.errors,
                 };
             }
             const writeResult = await this.client.writeFile({
                 workspaceId,
                 path,
-                content: this.renderContent(workspaceId, normalized, false),
+                content,
                 contentType: JSON_CONTENT_TYPE,
-                semantics: this.computeSemantics(normalized.objectType, normalized.objectId, normalized.payload),
+                semantics,
             });
+            await writeLinearAliases(this.client, workspaceId, normalized, path, content, semantics);
             const counts = inferWriteCounts(normalized, writeResult, false);
-            return {
-                filesWritten: counts.filesWritten,
-                filesUpdated: counts.filesUpdated,
+            const auxiliary = await this.writeAuxiliaryFiles(workspaceId, normalized, false);
+            const result = {
+                filesWritten: counts.filesWritten + auxiliary.filesWritten,
+                filesUpdated: counts.filesUpdated + auxiliary.filesUpdated,
                 filesDeleted: 0,
-                paths: [path],
-                errors: [],
+                paths: [path, ...auxiliary.paths],
+                errors: auxiliary.errors,
             };
+            if (normalized.objectType !== 'issue') {
+                return result;
+            }
+            const previousAliasPath = resolvePreviousIssueStateAliasPath(normalized.payload);
+            const aliasPath = resolveIssueStateAliasPath(normalized.payload);
+            if (previousAliasPath && previousAliasPath !== aliasPath) {
+                if (this.client.deleteFile) {
+                    await this.client.deleteFile({ workspaceId, path: previousAliasPath });
+                    result.filesDeleted += 1;
+                }
+                else {
+                    const previousDeleteResult = await this.client.writeFile({
+                        workspaceId,
+                        path: previousAliasPath,
+                        content: this.renderContent(workspaceId, normalized, true),
+                        contentType: JSON_CONTENT_TYPE,
+                        semantics,
+                    });
+                    const previousCounts = inferWriteCounts(normalized, previousDeleteResult, true);
+                    result.filesWritten += previousCounts.filesWritten;
+                    result.filesUpdated += previousCounts.filesUpdated;
+                    result.filesDeleted += previousCounts.filesDeleted;
+                }
+                result.paths.push(previousAliasPath);
+            }
+            if (!aliasPath) {
+                result.errors.push({
+                    path: aliasErrorPath,
+                    error: 'Linear issue is missing state_name or identifier for by-state alias emission.',
+                });
+                return result;
+            }
+            const aliasWriteResult = await this.client.writeFile({
+                workspaceId,
+                path: aliasPath,
+                content,
+                contentType: JSON_CONTENT_TYPE,
+                semantics,
+            });
+            const aliasCounts = inferWriteCounts(normalized, aliasWriteResult, false);
+            result.filesWritten += aliasCounts.filesWritten;
+            result.filesUpdated += aliasCounts.filesUpdated;
+            result.paths.push(aliasPath);
+            return result;
         }
         catch (error) {
             const fallbackPath = inferFallbackPath(event);
@@ -195,6 +284,69 @@ export class LinearAdapter extends IntegrationAdapter {
             payload: event.payload,
         });
     }
+    async writeAuxiliaryFiles(workspaceId, event, deleted) {
+        const result = {
+            filesWritten: 0,
+            filesUpdated: 0,
+            paths: [],
+            errors: [],
+        };
+        const layoutFile = linearLayoutPromptFile();
+        await this.recordAuxiliaryWrite(result, workspaceId, layoutFile.path, layoutFile.content, layoutFile.contentType);
+        const bucket = bucketForObjectType(event.objectType);
+        if (!bucket) {
+            return result;
+        }
+        const existingRows = await this.readIndexRows(workspaceId, buildIndexPathForBucket(bucket));
+        if (!existingRows) {
+            return result;
+        }
+        const nextRows = deleted
+            ? existingRows.filter((row) => row.id !== event.objectId)
+            : upsertLinearIndexRow(existingRows, buildIndexRow(bucket, event));
+        const indexFile = buildIndexFileForBucket(bucket, nextRows);
+        await this.recordAuxiliaryWrite(result, workspaceId, indexFile.path, indexFile.content, indexFile.contentType);
+        return result;
+    }
+    async readIndexRows(workspaceId, path) {
+        const content = await readClientFile(this.client, workspaceId, path);
+        if (content === READ_NOT_AVAILABLE) {
+            // No reader on the client — we can't reconcile, so skip the auxiliary write entirely.
+            return undefined;
+        }
+        if (content === undefined) {
+            // Reader ran but the index is missing/empty/malformed. Bootstrap with an empty
+            // array so the first ingest writes the index instead of getting stuck.
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(content);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async recordAuxiliaryWrite(result, workspaceId, path, content, contentType) {
+        try {
+            const writeResult = await this.client.writeFile({
+                workspaceId,
+                path,
+                content,
+                contentType,
+            });
+            const counts = inferAuxiliaryWriteCounts(writeResult);
+            result.filesWritten += counts.filesWritten;
+            result.filesUpdated += counts.filesUpdated;
+            result.paths.push(path);
+        }
+        catch (error) {
+            result.errors.push({
+                path,
+                error: toErrorMessage(error),
+            });
+        }
+    }
 }
 function applyIssueSemantics(properties, relations, payload) {
     const issue = payload;
@@ -267,12 +419,12 @@ function applyIssueSemantics(properties, relations, payload) {
         addStringProperty(properties, 'linear.cycle_name', issue.cycle.name);
     }
     if (issue.parent?.id) {
-        relations.add(linearIssuePath(issue.parent.id));
+        relations.add(buildLinearIssueReferencePath(issue.parent));
         addStringProperty(properties, 'linear.parent_id', issue.parent.id);
     }
     for (const child of issue.children ?? []) {
         if (child.id) {
-            relations.add(linearIssuePath(child.id));
+            relations.add(buildLinearIssueReferencePath(child));
         }
     }
     for (const relation of asRelations(issue.relations)) {
@@ -294,11 +446,15 @@ function applyIssueSemantics(properties, relations, payload) {
     addFirstStringProperty(properties, 'linear.team_key', properties['linear.team_key'], issue.team_key);
     addFirstStringProperty(properties, 'linear.team_name', properties['linear.team_name'], issue.team_name);
 }
-function readIssueTitle(objectType, payload) {
-    if (normalizeLinearObjectType(objectType) !== 'issue') {
-        return undefined;
+function readPathHumanReadable(objectType, payload) {
+    switch (normalizeLinearObjectType(objectType)) {
+        case 'issue':
+            return getLinearIssueHumanReadable(buildLinearIssueHumanReadableInput(payload));
+        case 'comment':
+            return getLinearCommentHumanReadable(buildLinearCommentHumanReadableInput(payload));
+        default:
+            return undefined;
     }
-    return asString(payload.title);
 }
 function applyCommentSemantics(properties, relations, comments, payload) {
     const comment = payload;
@@ -323,7 +479,7 @@ function applyCommentSemantics(properties, relations, comments, payload) {
     addFirstStringProperty(properties, 'linear.author_name', properties['linear.author_name'], comment.user_name, comment.author_name);
     addFirstStringProperty(properties, 'linear.author_email', properties['linear.author_email'], comment.user_email, comment.author_email);
     if (comment.issue?.id) {
-        relations.add(linearIssuePath(comment.issue.id));
+        relations.add(buildLinearIssueReferencePath(comment.issue));
         addStringProperty(properties, 'linear.issue_id', comment.issue.id);
         addStringProperty(properties, 'linear.issue_identifier', comment.issue.identifier);
         addStringProperty(properties, 'linear.issue_title', comment.issue.title);
@@ -331,7 +487,10 @@ function applyCommentSemantics(properties, relations, comments, payload) {
     }
     const issueId = asString(comment.issue_id);
     if (issueId) {
-        relations.add(linearIssuePath(issueId));
+        relations.add(linearIssuePath(issueId, getLinearIssueHumanReadable(buildLinearIssueHumanReadableInput({
+            identifier: comment.issue_identifier,
+            title: comment.issue_title,
+        }))));
         addStringProperty(properties, 'linear.issue_id', issueId);
     }
     addFirstStringProperty(properties, 'linear.issue_identifier', properties['linear.issue_identifier'], comment.issue_identifier);
@@ -369,6 +528,29 @@ function applyProjectSemantics(properties, relations, payload) {
         }
     }
 }
+function buildLinearIssueReferencePath(issue) {
+    return linearIssuePath(issue.id, getLinearIssueHumanReadable(issue));
+}
+function buildLinearIssueHumanReadableInput(record) {
+    const identifier = asString(record.identifier);
+    const title = asString(record.title);
+    return {
+        ...(identifier ? { identifier } : {}),
+        ...(title ? { title } : {}),
+    };
+}
+function buildLinearCommentIssueInput(issue) {
+    const identifier = asString(issue?.identifier);
+    return identifier ? { identifier } : undefined;
+}
+function buildLinearCommentHumanReadableInput(record) {
+    const body = asString(record.body);
+    const issue = buildLinearCommentIssueInput(getRecord(record.issue));
+    return {
+        ...(body ? { body } : {}),
+        ...(issue ? { issue } : {}),
+    };
+}
 function applyCycleSemantics(properties, payload) {
     const cycle = payload;
     addNumberProperty(properties, 'linear.number', cycle.number);
@@ -467,12 +649,90 @@ function mergeLinearPayload(event) {
         }),
     };
 }
+function bucketForObjectType(objectType) {
+    switch (normalizeLinearObjectType(objectType)) {
+        case 'issue':
+            return 'issues';
+        case 'comment':
+            return 'comments';
+        case 'team':
+            return 'teams';
+        case 'user':
+            return 'users';
+        default:
+            return undefined;
+    }
+}
+function buildIndexRow(bucket, event) {
+    const payload = {
+        ...event.payload,
+        id: event.objectId,
+    };
+    switch (bucket) {
+        case 'issues':
+            return linearIssueIndexRow(payload);
+        case 'comments':
+            return linearCommentIndexRow(payload);
+        case 'teams':
+            return linearTeamIndexRow(payload);
+        case 'users':
+            return linearUserIndexRow(payload);
+    }
+}
+function buildIndexFileForBucket(bucket, rows) {
+    switch (bucket) {
+        case 'issues':
+            return buildLinearIndexFile('issues', rows);
+        case 'comments':
+            return buildLinearIndexFile('comments', rows);
+        case 'teams':
+            return buildLinearIndexFile('teams', rows);
+        case 'users':
+            return buildLinearIndexFile('users', rows);
+    }
+}
+function buildIndexPathForBucket(bucket) {
+    return buildIndexFileForBucket(bucket, []).path;
+}
+function upsertLinearIndexRow(rows, row) {
+    return [...rows.filter((existing) => existing.id !== row.id), row];
+}
+// `READ_NOT_AVAILABLE` is returned when the client cannot read at all (no
+// `readFile` method). `undefined` means the call ran but the file is missing
+// or the response was malformed. Callers use this distinction to decide
+// whether to skip auxiliary writes (no readFile) or bootstrap an empty index
+// (file missing on first ingest).
+const READ_NOT_AVAILABLE = Symbol('readNotAvailable');
+async function readClientFile(client, workspaceId, path) {
+    if (!client.readFile) {
+        return READ_NOT_AVAILABLE;
+    }
+    try {
+        const value = client.readFile.length >= 2
+            ? await client.readFile(workspaceId, path)
+            : await client.readFile({ workspaceId, path });
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (value && typeof value === 'object' && typeof value.content === 'string') {
+            return value.content;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function inferAuxiliaryWriteCounts(writeResult) {
+    if (writeResult?.created || writeResult?.status === 'created') {
+        return { filesWritten: 1, filesUpdated: 0 };
+    }
+    return { filesWritten: 0, filesUpdated: 1 };
+}
 function inferWriteCounts(event, writeResult, deleted) {
     if (deleted) {
-        if (writeResult?.status === 'created' || writeResult?.created) {
-            return { filesWritten: 1, filesUpdated: 0, filesDeleted: 0 };
-        }
-        return { filesWritten: 0, filesUpdated: 1, filesDeleted: 0 };
+        void writeResult;
+        return { filesWritten: 0, filesUpdated: 0, filesDeleted: 1 };
     }
     if (writeResult?.created || writeResult?.status === 'created') {
         return { filesWritten: 1, filesUpdated: 0, filesDeleted: 0 };
@@ -511,6 +771,33 @@ function inferFallbackPath(event) {
         return '';
     }
 }
+function resolveIssueStateAliasPath(payload) {
+    const stateName = asString(payload.state_name);
+    const identifier = asString(payload.identifier);
+    if (!stateName || !identifier) {
+        return undefined;
+    }
+    return linearIssueByStatePath(stateName, identifier);
+}
+function resolvePreviousIssueStateAliasPath(payload) {
+    const previousData = getRecord(getRecord(payload._webhook)?.previousData);
+    if (!previousData) {
+        return undefined;
+    }
+    const stateName = asString(previousData.state_name);
+    const identifier = asString(previousData.identifier) ?? asString(payload.identifier);
+    if (!stateName || !identifier) {
+        return undefined;
+    }
+    return linearIssueByStatePath(stateName, identifier);
+}
+function inferIssueStateAliasErrorPath(event) {
+    const identifier = asString(event.payload.identifier);
+    if (identifier) {
+        return `/linear/issues/by-state/<missing-state>/${encodeURIComponent(identifier)}.json`;
+    }
+    return '/linear/issues/by-state/<missing-state>/<missing-identifier>.json';
+}
 function extractPayloadId(value) {
     const record = getRecord(value);
     return asString(record?.id);
@@ -571,6 +858,88 @@ function sortStrings(values) {
 function stableJson(value) {
     return `${JSON.stringify(sortJson(value), null, 2)}\n`;
 }
+async function writeLinearAliases(client, workspaceId, event, canonicalPath, content, semantics) {
+    // duplicate write — the adapter only has a file-write interface, so aliases store the canonical bytes verbatim.
+    const normalizedType = normalizeLinearObjectType(event.objectType);
+    if (normalizedType !== 'issue' && normalizedType !== 'project') {
+        return;
+    }
+    const scope = normalizedType === 'issue' ? `${LINEAR_PATH_ROOT}/issues` : `${LINEAR_PATH_ROOT}/projects`;
+    const title = normalizedType === 'issue' ? asString(event.payload.title) : asString(event.payload.name);
+    const byId = normalizedType === 'issue'
+        ? asString(event.payload.identifier) ?? event.objectId
+        : event.objectId;
+    await writeLinearIndex(client, workspaceId, scope);
+    await writeLinearFile(client, workspaceId, linearByIdAliasPath(scope, byId), content, semantics);
+    if (!title) {
+        return;
+    }
+    const baseAliasPath = linearByTitleAliasPath(scope, title, event.objectId);
+    const existingBaseContent = await readLinearFile(client, baseAliasPath);
+    const aliasPath = existingBaseContent !== undefined && existingBaseContent !== content
+        ? linearByTitleAliasPath(scope, title, event.objectId, true)
+        : baseAliasPath;
+    // TODO(issue #106): remove stale by-title aliases when a record title changes on re-ingest; this wave only writes the current alias.
+    await writeLinearFile(client, workspaceId, aliasPath, content, semantics);
+}
+async function writeLinearIndex(client, workspaceId, scope) {
+    const indexPath = `${scope}/_index.json`;
+    const rows = mergeLinearIndexRows(await readLinearFile(client, indexPath), [
+        { title: 'by-id', file: 'by-id/' },
+        { title: 'by-title', file: 'by-title/' },
+    ]);
+    await writeLinearFile(client, workspaceId, indexPath, stableJson({ rows }), undefined);
+}
+function mergeLinearIndexRows(existingContent, requiredRows) {
+    const rows = new Map();
+    for (const row of parseLinearIndexRows(existingContent)) {
+        rows.set(row.file, row);
+    }
+    for (const row of requiredRows) {
+        rows.set(row.file, row);
+    }
+    return [...rows.values()].sort((left, right) => left.file.localeCompare(right.file));
+}
+function parseLinearIndexRows(existingContent) {
+    if (!existingContent) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(existingContent);
+        return Array.isArray(parsed.rows)
+            ? parsed.rows.filter((row) => typeof row?.file === 'string' && typeof row?.title === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function writeLinearFile(client, workspaceId, path, content, semantics) {
+    await client.writeFile({
+        workspaceId,
+        path,
+        content,
+        contentType: JSON_CONTENT_TYPE,
+        ...(semantics ? { semantics } : {}),
+    });
+}
+async function readLinearFile(client, path) {
+    const reader = client.readFile;
+    if (typeof reader !== 'function') {
+        return undefined;
+    }
+    try {
+        const value = await reader.call(client, path);
+        return typeof value === 'string'
+            ? value
+            : value && typeof value === 'object' && 'content' in value && typeof value.content === 'string'
+                ? value.content
+                : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function sortJson(value) {
     if (Array.isArray(value)) {
         return value.map(sortJson);
@@ -628,7 +997,8 @@ function asLinearReferenceIds(value) {
         .filter((entry) => entry !== undefined);
 }
 function uniqueStrings(values) {
-    return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right));
+    return Array.from(new Set(values.filter((value) => Boolean(value))))
+        .sort((left, right) => left.localeCompare(right));
 }
 function mapPriorityLabel(priority) {
     switch (priority) {