chief-clancy 0.2.0-beta.3 → 0.3.0

package/dist/scripts/board/jira/jira.js

@@ -0,0 +1,251 @@
+/**
+ * Clancy Jira board script.
+ *
+ * Fetches a ticket from Jira Cloud, creates branches, invokes Claude,
+ * squash merges, transitions status, and sends notifications.
+ *
+ * Uses the new POST `/rest/api/3/search/jql` endpoint (old GET `/search`
+ * was removed by Atlassian in August 2025).
+ */
+import { jiraSearchResponseSchema, jiraTransitionsResponseSchema, } from '../../../schemas/jira.js';
+import { jiraHeaders, pingEndpoint } from '../../../scripts/shared/http/http.js';
+const SAFE_VALUE_PATTERN = /^[a-zA-Z0-9 _\-'.]+$/;
+const ISSUE_KEY_PATTERN = /^[A-Z][A-Z0-9]+-\d+$/;
+/**
+ * Build Jira Basic auth header value.
+ *
+ * @param user - The Jira username (email).
+ * @param token - The Jira API token.
+ * @returns The Base64-encoded `user:token` string for Basic auth.
+ */
+export function buildAuthHeader(user, token) {
+    return Buffer.from(`${user}:${token}`).toString('base64');
+}
+/**
+ * Validate that a user-controlled value is safe for JQL injection.
+ *
+ * @param value - The value to validate.
+ * @returns `true` if the value matches the safe pattern.
+ */
+export function isSafeJqlValue(value) {
+    return SAFE_VALUE_PATTERN.test(value);
+}
+/**
+ * Ping the Jira API to verify connectivity and credentials.
+ *
+ * @param baseUrl - The Jira Cloud base URL.
+ * @param projectKey - The Jira project key.
+ * @param auth - The Base64-encoded Basic auth string.
+ * @returns An object with `ok` and optional `error` message.
+ *
+ * @example
+ * ```ts
+ * const result = await pingJira('https://example.atlassian.net', 'PROJ', authHeader);
+ * if (!result.ok) console.error(result.error);
+ * ```
+ */
+export async function pingJira(baseUrl, projectKey, auth) {
+    return pingEndpoint(`${baseUrl}/rest/api/3/project/${projectKey}`, jiraHeaders(auth), {
+        401: '✗ Jira auth failed — check credentials',
+        403: '✗ Jira permission denied for this project',
+        404: `✗ Jira project "${projectKey}" not found`,
+    }, '✗ Could not reach Jira — check network');
+}
+/**
+ * Build the JQL query for fetching the next ticket.
+ *
+ * @param projectKey - The Jira project key.
+ * @param status - The JQL status to filter by (default: `"To Do"`).
+ * @param sprint - If set, adds an open sprint filter.
+ * @param label - If set, adds a label filter.
+ * @returns The JQL query string.
+ */
+export function buildJql(projectKey, status, sprint, label) {
+    const parts = [`project="${projectKey}"`];
+    if (sprint)
+        parts.push('sprint in openSprints()');
+    if (label)
+        parts.push(`labels = "${label}"`);
+    parts.push(`assignee=currentUser()`);
+    parts.push(`status="${status}"`);
+    parts.push('ORDER BY priority ASC');
+    return parts.join(' AND ');
+}
+/**
+ * Extract all text strings from a Jira ADF (Atlassian Document Format) description.
+ *
+ * Recursively walks the ADF tree and collects all string values.
+ *
+ * @param adf - The ADF description object (or `undefined`).
+ * @returns A single string with all text content joined by spaces.
+ */
+export function extractAdfText(adf) {
+    if (!adf || typeof adf !== 'object')
+        return '';
+    const strings = [];
+    function walk(node) {
+        if (typeof node === 'string') {
+            strings.push(node);
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (node && typeof node === 'object') {
+            for (const value of Object.values(node)) {
+                walk(value);
+            }
+        }
+    }
+    walk(adf);
+    return strings.join(' ');
+}
+/**
+ * Fetch the next available ticket from Jira.
+ *
+ * @param baseUrl - The Jira Cloud base URL.
+ * @param auth - The Base64-encoded Basic auth string.
+ * @param projectKey - The Jira project key.
+ * @param status - The JQL status to filter by.
+ * @param sprint - Optional sprint filter.
+ * @param label - Optional label filter.
+ * @returns The fetched ticket, or `undefined` if no tickets are available.
+ */
+export async function fetchTicket(baseUrl, auth, projectKey, status, sprint, label) {
+    const jql = buildJql(projectKey, status, sprint, label);
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/rest/api/3/search/jql`, {
+            method: 'POST',
+            headers: {
+                ...jiraHeaders(auth),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                jql,
+                maxResults: 1,
+                fields: [
+                    'summary',
+                    'description',
+                    'issuelinks',
+                    'parent',
+                    'customfield_10014',
+                ],
+            }),
+        });
+    }
+    catch (err) {
+        console.warn(`⚠ Jira API request failed: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    if (!response.ok) {
+        console.warn(`⚠ Jira API returned HTTP ${response.status}`);
+        return undefined;
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        console.warn('⚠ Jira API returned invalid JSON');
+        return undefined;
+    }
+    const parsed = jiraSearchResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        console.warn(`⚠ Unexpected Jira response shape: ${parsed.error.message}`);
+        return undefined;
+    }
+    if (!parsed.data.issues.length)
+        return undefined;
+    const issue = parsed.data.issues[0];
+    const fields = issue.fields;
+    // Extract blockers
+    const blockers = (fields.issuelinks ?? [])
+        .filter((link) => link.type?.name === 'Blocks' && link.inwardIssue?.key)
+        .map((link) => link.inwardIssue?.key)
+        .filter((key) => Boolean(key));
+    // Extract epic (next-gen parent OR classic customfield)
+    const epicKey = fields.parent?.key ?? fields.customfield_10014 ?? undefined;
+    return {
+        key: issue.key,
+        title: fields.summary,
+        description: extractAdfText(fields.description),
+        provider: 'jira',
+        epicKey,
+        blockers,
+    };
+}
+/**
+ * Look up a Jira transition ID by status name.
+ *
+ * @param baseUrl - The Jira Cloud base URL.
+ * @param auth - The Base64-encoded Basic auth string.
+ * @param issueKey - The Jira issue key (e.g., `'PROJ-123'`).
+ * @param statusName - The target status name (e.g., `'In Progress'`).
+ * @returns The transition ID, or `undefined` if not found.
+ */
+export async function lookupTransitionId(baseUrl, auth, issueKey, statusName) {
+    if (!ISSUE_KEY_PATTERN.test(issueKey))
+        return undefined;
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/rest/api/3/issue/${issueKey}/transitions`, { headers: jiraHeaders(auth) });
+    }
+    catch (err) {
+        console.warn(`⚠ Jira transitions request failed: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    if (!response.ok)
+        return undefined;
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        console.warn('⚠ Jira transitions returned invalid JSON');
+        return undefined;
+    }
+    const parsed = jiraTransitionsResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        console.warn(`⚠ Unexpected Jira transitions response: ${parsed.error.message}`);
+        return undefined;
+    }
+    const transition = parsed.data.transitions.find((t) => t.name === statusName);
+    return transition?.id;
+}
+/**
+ * Transition a Jira issue to a new status.
+ *
+ * Fetches available transitions and executes the one matching the target status name.
+ * Best-effort — never throws on failure.
+ *
+ * @param baseUrl - The Jira Cloud base URL.
+ * @param auth - The Base64-encoded Basic auth string.
+ * @param issueKey - The Jira issue key (e.g., `'PROJ-123'`).
+ * @param statusName - The target status name (e.g., `'In Progress'`).
+ * @returns `true` if the transition succeeded.
+ */
+export async function transitionIssue(baseUrl, auth, issueKey, statusName) {
+    try {
+        const transitionId = await lookupTransitionId(baseUrl, auth, issueKey, statusName);
+        if (!transitionId) {
+            console.warn(`⚠ Jira transition "${statusName}" not found for ${issueKey}`);
+            return false;
+        }
+        const response = await fetch(`${baseUrl}/rest/api/3/issue/${issueKey}/transitions`, {
+            method: 'POST',
+            headers: {
+                ...jiraHeaders(auth),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ transition: { id: transitionId } }),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=jira.js.map

package/dist/scripts/board/jira/jira.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jira.js","sourceRoot":"","sources":["../../../../src/scripts/board/jira/jira.ts"],"names":[],"mappings":"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"}

package/dist/scripts/board/linear/linear.d.ts

@@ -0,0 +1,85 @@
+import type { Ticket } from '../../../types/index.js';
+type LinearEnv = {
+    LINEAR_API_KEY: string;
+    LINEAR_TEAM_ID: string;
+    CLANCY_LABEL?: string;
+    CLANCY_BASE_BRANCH?: string;
+    CLANCY_STATUS_IN_PROGRESS?: string;
+    CLANCY_STATUS_DONE?: string;
+    CLANCY_MODEL?: string;
+    CLANCY_NOTIFY_WEBHOOK?: string;
+};
+/**
+ * Validate that a team ID is safe for use in GraphQL variables.
+ *
+ * @param teamId - The Linear team ID to validate.
+ * @returns `true` if the ID matches the safe pattern.
+ */
+export declare function isValidTeamId(teamId: string): boolean;
+/**
+ * Make a GraphQL request to the Linear API.
+ *
+ * Personal API keys are passed directly (no "Bearer" prefix).
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param query - The GraphQL query string.
+ * @param variables - The GraphQL variables object.
+ * @returns The raw JSON response, or `undefined` on failure.
+ */
+export declare function linearGraphql(apiKey: string, query: string, variables?: Record<string, unknown>): Promise<unknown>;
+/**
+ * Ping the Linear API to verify connectivity and credentials.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @returns An object with `ok` and optional `error` message.
+ */
+export declare function pingLinear(apiKey: string): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Fetch the next available issue from Linear.
+ *
+ * Filters by `state.type: "unstarted"` (enum, works regardless of team
+ * column naming) and optionally by label.
+ *
+ * @param env - The Linear environment variables.
+ * @returns The fetched ticket with optional parent info, or `undefined` if none available.
+ */
+export declare function fetchIssue(env: LinearEnv): Promise<(Ticket & {
+    issueId: string;
+    parentIdentifier?: string;
+}) | undefined>;
+/**
+ * Look up a Linear workflow state ID by name and team.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param teamId - The Linear team ID.
+ * @param stateName - The workflow state name (e.g., `'In Progress'`).
+ * @returns The state ID, or `undefined` if not found.
+ */
+export declare function lookupWorkflowStateId(apiKey: string, teamId: string, stateName: string): Promise<string | undefined>;
+/**
+ * Execute a state transition on a Linear issue.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param issueId - The Linear issue internal ID.
+ * @param stateId - The target workflow state ID.
+ * @returns `true` if the mutation succeeded.
+ */
+export declare function executeStateTransition(apiKey: string, issueId: string, stateId: string): Promise<boolean>;
+/**
+ * Transition a Linear issue to a new workflow state.
+ *
+ * Looks up the workflow state ID by name, then executes the `issueUpdate` mutation.
+ * Best-effort — never throws on failure.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param teamId - The Linear team ID.
+ * @param issueId - The Linear issue internal ID.
+ * @param stateName - The target workflow state name (e.g., `'In Progress'`).
+ * @returns `true` if the transition succeeded.
+ */
+export declare function transitionIssue(apiKey: string, teamId: string, issueId: string, stateName: string): Promise<boolean>;
+export {};
+//# sourceMappingURL=linear.d.ts.map

package/dist/scripts/board/linear/linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear.d.ts","sourceRoot":"","sources":["../../../../src/scripts/board/linear/linear.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAK/C,KAAK,SAAS,GAAG;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,OAAO,CAAC,CA8BlB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAO1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CACrD,CAAC,MAAM,GAAG;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC,GACF,SAAS,CACZ,CA0DA;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuB7B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/dist/scripts/board/linear/linear.js

@@ -0,0 +1,209 @@
+/**
+ * Clancy Linear board script.
+ *
+ * Fetches an issue from Linear's GraphQL API, creates branches,
+ * invokes Claude, squash merges, transitions status, and sends notifications.
+ *
+ * Important: Linear personal API keys do NOT use "Bearer" prefix.
+ * Only OAuth tokens use "Bearer". This is intentional per Linear docs.
+ */
+import { linearIssueUpdateResponseSchema, linearIssuesResponseSchema, linearViewerResponseSchema, linearWorkflowStatesResponseSchema, } from '../../../schemas/linear.js';
+const SAFE_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const LINEAR_API_URL = 'https://api.linear.app/graphql';
+/**
+ * Validate that a team ID is safe for use in GraphQL variables.
+ *
+ * @param teamId - The Linear team ID to validate.
+ * @returns `true` if the ID matches the safe pattern.
+ */
+export function isValidTeamId(teamId) {
+    return SAFE_ID_PATTERN.test(teamId);
+}
+/**
+ * Make a GraphQL request to the Linear API.
+ *
+ * Personal API keys are passed directly (no "Bearer" prefix).
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param query - The GraphQL query string.
+ * @param variables - The GraphQL variables object.
+ * @returns The raw JSON response, or `undefined` on failure.
+ */
+export async function linearGraphql(apiKey, query, variables) {
+    let response;
+    try {
+        response = await fetch(LINEAR_API_URL, {
+            method: 'POST',
+            headers: {
+                Authorization: apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ query, variables }),
+        });
+    }
+    catch (err) {
+        console.warn(`⚠ Linear API request failed: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    if (!response.ok) {
+        console.warn(`⚠ Linear API returned HTTP ${response.status}`);
+        return undefined;
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        console.warn('⚠ Linear API returned invalid JSON');
+        return undefined;
+    }
+}
+/**
+ * Ping the Linear API to verify connectivity and credentials.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @returns An object with `ok` and optional `error` message.
+ */
+export async function pingLinear(apiKey) {
+    const raw = await linearGraphql(apiKey, '{ viewer { id } }');
+    const parsed = linearViewerResponseSchema.safeParse(raw);
+    if (parsed.success && parsed.data.data?.viewer?.id)
+        return { ok: true };
+    return { ok: false, error: '✗ Linear auth failed — check LINEAR_API_KEY' };
+}
+/**
+ * Fetch the next available issue from Linear.
+ *
+ * Filters by `state.type: "unstarted"` (enum, works regardless of team
+ * column naming) and optionally by label.
+ *
+ * @param env - The Linear environment variables.
+ * @returns The fetched ticket with optional parent info, or `undefined` if none available.
+ */
+export async function fetchIssue(env) {
+    const label = env.CLANCY_LABEL?.trim();
+    const hasLabel = Boolean(label);
+    const labelFilter = hasLabel ? 'labels: { name: { eq: $label } }' : '';
+    const query = `
+    query($teamId: String!${hasLabel ? ', $label: String!' : ''}) {
+      viewer {
+        assignedIssues(
+          filter: {
+            state: { type: { eq: "unstarted" } }
+            team: { id: { eq: $teamId } }
+            ${labelFilter}
+          }
+          first: 1
+          orderBy: priority
+        ) {
+          nodes {
+            id
+            identifier
+            title
+            description
+            parent { identifier title }
+          }
+        }
+      }
+    }
+  `;
+    const variables = {
+        teamId: env.LINEAR_TEAM_ID,
+    };
+    if (hasLabel)
+        variables.label = label;
+    const raw = await linearGraphql(env.LINEAR_API_KEY, query, variables);
+    const parsed = linearIssuesResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        console.warn(`⚠ Unexpected Linear response shape: ${parsed.error.message}`);
+        return undefined;
+    }
+    const nodes = parsed.data.data?.viewer?.assignedIssues?.nodes;
+    if (!nodes?.length)
+        return undefined;
+    const issue = nodes[0];
+    return {
+        key: issue.identifier,
+        title: issue.title,
+        description: issue.description ?? '',
+        provider: 'linear',
+        issueId: issue.id,
+        parentIdentifier: issue.parent?.identifier,
+    };
+}
+/**
+ * Look up a Linear workflow state ID by name and team.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param teamId - The Linear team ID.
+ * @param stateName - The workflow state name (e.g., `'In Progress'`).
+ * @returns The state ID, or `undefined` if not found.
+ */
+export async function lookupWorkflowStateId(apiKey, teamId, stateName) {
+    const query = `
+    query($teamId: String!, $name: String!) {
+      workflowStates(filter: {
+        team: { id: { eq: $teamId } }
+        name: { eq: $name }
+      }) {
+        nodes { id }
+      }
+    }
+  `;
+    const raw = await linearGraphql(apiKey, query, { teamId, name: stateName });
+    const parsed = linearWorkflowStatesResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        console.warn(`⚠ Unexpected Linear workflowStates response: ${parsed.error.message}`);
+        return undefined;
+    }
+    return parsed.data.data?.workflowStates?.nodes?.[0]?.id;
+}
+/**
+ * Execute a state transition on a Linear issue.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param issueId - The Linear issue internal ID.
+ * @param stateId - The target workflow state ID.
+ * @returns `true` if the mutation succeeded.
+ */
+export async function executeStateTransition(apiKey, issueId, stateId) {
+    const mutation = `
+    mutation($issueId: String!, $stateId: String!) {
+      issueUpdate(id: $issueId, input: { stateId: $stateId }) {
+        success
+      }
+    }
+  `;
+    const raw = await linearGraphql(apiKey, mutation, { issueId, stateId });
+    const parsed = linearIssueUpdateResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        console.warn(`⚠ Unexpected Linear issueUpdate response: ${parsed.error.message}`);
+        return false;
+    }
+    return parsed.data.data?.issueUpdate?.success === true;
+}
+/**
+ * Transition a Linear issue to a new workflow state.
+ *
+ * Looks up the workflow state ID by name, then executes the `issueUpdate` mutation.
+ * Best-effort — never throws on failure.
+ *
+ * @param apiKey - The Linear personal API key.
+ * @param teamId - The Linear team ID.
+ * @param issueId - The Linear issue internal ID.
+ * @param stateName - The target workflow state name (e.g., `'In Progress'`).
+ * @returns `true` if the transition succeeded.
+ */
+export async function transitionIssue(apiKey, teamId, issueId, stateName) {
+    try {
+        const stateId = await lookupWorkflowStateId(apiKey, teamId, stateName);
+        if (!stateId) {
+            console.warn(`⚠ Linear workflow state "${stateName}" not found — check team configuration`);
+            return false;
+        }
+        return await executeStateTransition(apiKey, issueId, stateId);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=linear.js.map

package/dist/scripts/board/linear/linear.js.map

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

package/dist/scripts/once/once.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run the once orchestrator — full ticket lifecycle.
+ *
+ * @param argv - Process arguments (supports `--dry-run` flag).
+ *
+ * @example
+ * ```ts
+ * await run(process.argv);
+ * ```
+ */
+export declare function run(argv: string[]): Promise<void>;
+//# sourceMappingURL=once.d.ts.map

package/dist/scripts/once/once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../../src/scripts/once/once.ts"],"names":[],"mappings":"AAoPA;;;;;;;;;GASG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0NvD"}